On Thu, Feb 07, 2019 at 09:09:49AM -0500, Edwin Zimmerman wrote:

quoted

quoted

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...