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

[Al Viro]

On Thu, Feb 07, 2019 at 09:09:49AM -0500, Edwin Zimmerman wrote:
> > > 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"

Um...   The _type_ of argument is visible in declaration already;
it doesn't say a damn thing about the value of that argument.

In this particular case, dentry/mnt pair (whichever way it gets
passed; struct path is exactly such a pair) is actually used to
specify the location of file or directory in question, but
try to guess that by description given in this "documentation"...

As for "defined in"... that's what grep/ctags/etc. are for.
Again, the useful information about an argument is _what_ gets
passed in it, not just which type it is...