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@xxxxxxxxxx> --- 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
