Messages in this thread Patch in this message | | | From | "Tobin C. Harding" <> | Subject | [PATCH v3 07/24] fs: Fix function docstring for posix_acl_update_mode() | Date | Wed, 27 Mar 2019 16:17:00 +1100 |
| |
Sphinx emits a bunch of warnings due to undocumented function parameters for posix_acl_update_mode(). We should document all the parameters.
Docstring is currently stale in places, it references a non-existent function, inode_change_ok(). As noted in the documentation file Documentation/filesystems/Porting this function is now called setattr_prepare().
Currently docstring includes 'setgit bit', meaning is not totally clear (to me), setattr_prepare() uses term 'SGID bit', let's use this too.
Fix function docstring for posix_acl_update_mode():
- Document function parameters. - Reference setattr_prepare() instead of inode_change_ok(). - Use 'SGID bit' instead of 'setgit bit'.
Signed-off-by: Tobin C. Harding <tobin@kernel.org> --- fs/posix_acl.c | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/fs/posix_acl.c b/fs/posix_acl.c index 2fd0fde16fe1..07394510c3d6 100644 --- a/fs/posix_acl.c +++ b/fs/posix_acl.c @@ -629,14 +629,18 @@ posix_acl_create(struct inode *dir, umode_t *mode, EXPORT_SYMBOL_GPL(posix_acl_create); /** - * posix_acl_update_mode - update mode in set_acl + * posix_acl_update_mode() - Update mode in set_acl. + * @inode: The inode we are working on. + * @mode_p: New mode to use when updating. + * @acl: ACL we are operating on. * - * Update the file mode when setting an ACL: compute the new file permission - * bits based on the ACL. In addition, if the ACL is equivalent to the new - * file mode, set *acl to NULL to indicate that no ACL should be set. + * Update the file mode when setting an ACL, compute the new file + * permission bits based on the ACL. In addition, if the ACL is + * equivalent to the new file mode, set ``*acl`` to %NULL to indicate + * that no ACL should be set. * - * As with chmod, clear the setgit bit if the caller is not in the owning group - * or capable of CAP_FSETID (see inode_change_ok). + * As with chmod, clear the SGID bit if the caller is not in the owning + * group or capable of CAP_FSETID (see setattr_prepare()). * * Called from set_acl inode operations. */ -- 2.21.0
| |