Re: [PATCH 06/10] security: fix documentation for the path_chmod hook

[Stephen Smalley]

On 2/7/19 9:32 AM, Stephen Smalley wrote:
> On 2/7/19 9:09 AM, Edwin Zimmerman wrote:
> > On Thursday, February 07, 2019 8:50 AM Al Viro wrote:
> > > On Thu, Feb 07, 2019 at 03:44:54PM +0300, Denis Efremov wrote:
> > > > The path_chmod hook was changed in the commit
> > > > "switch security_path_chmod() to struct path *" (cdcf116d44e7).
> > > > The argument @mnt was removed from the hook, @dentry was changed
> > > > to @path. This patch updates the documentation accordingly.
> > > >
> > > > Signed-off-by: Denis Efremov <efremov@xxxxxxxxx>
> > > > ---
> > > > Â include/linux/lsm_hooks.h | 3 +--
> > > > Â 1 file changed, 1 insertion(+), 2 deletions(-)
> > > >
> > > > diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
> > > > index cb93972257be..5d6428d0027b 100644
> > > > --- a/include/linux/lsm_hooks.h
> > > > +++ b/include/linux/lsm_hooks.h
> > > > @@ -304,8 +304,7 @@
> > > > ÂÂ *ÂÂÂ Return 0 if permission is granted.
> > > > ÂÂ * @path_chmod:
> > > > ÂÂ *ÂÂÂ Check for permission to change DAC's permission of a file or 
> > > > directory.
> > > > - *ÂÂÂ @dentry contains the dentry structure.
> > > > - *ÂÂÂ @mnt contains the vfsmnt structure.
> > > > + *ÂÂÂ @path contains the path structure.
> > >
> > > May I politely inquire about the value of these comments? How much 
> > > information
> > > is provided by refering to an argument as "the dentry structure" or 
> > > "the path
> > > structure", especially when there's nothing immediately above that 
> > > would introduce
> > > either. "Type of 'dentry' argument is somehow related to struct dentry,
> > > try and guess what the value might be - we don't care, we just need 
> > > every
> > > argument commented"?
> > >
> > > Who needs that crap in the first place?
> >
> > The comments fill a valuable place to folks like me who are new to the 
> > linux security modules.
> > In my spare time, I'm writing a new LSM specifically geared for 
> > parental controls uses, and the
> > comments in lsm_hooks.h have helped me out more than once. Perhaps 
> > the comments could
> > be inproved by changing them to something like this:
> > "@[arg] contains the [type] structure, defined in linux/[?].h"
>
> I don't think so. The point is not what type of structure but what 
> object is being passed and why is it relevant to the hook, e.g.
>
> + @path contains the path structure for the file whose permissions are 
> being modified
>
> or similar.

It would probably be better to amend the description too to refer to the 
argument in context, e.g.

* @path_chmod:
*     Check for permission to change the mode of the file referenced by 
@path.
*     @path the file whose mode would be modified

or similar.

I'd suggest looking to kerneldoc comments in fs/*.c or elsewhere as 
better examples.