Re: Proposed documentation patch to security.h

chrisat_private

* Greg KH (gregat_private) wrote:
> Hi all,
> 
> Here's my latest try at converting a tiny portion of the security.h
> comments to the proper kernel-doc format.  This time, there can't be any
> discussion that "our format is better" as it is not in proper kernel-doc
> style.
> 
> This patch only converts the struct module_security_ops to the new
> format.  An example of what the converted output looks like can be found
> at http://lsm.immunix.org/~greg/module_security_ops.html
> It was generated by typing:
> 	perl scripts/kernel-doc -html include/linux/security.h > module_security_ops.html
> 
> Let me know if anyone has any problems with this.  And if so,
> constructive counter proposals are encouraged :)

looks alright...minor nitpick...

>   * struct module_security_ops - Security hooks for kernel module operations.
> + * @create_module:
> + *	Check the permission before allocating space for a module.
> + *	name contains the module name.
	@name
> + *	size contains the module size.
	@size
> + *	Return 0 if permission is granted.
> + * @init_module:
> + * 	Check permission before initializing a module.
> + * 	mod contains a pointer to the module being initialized.
	@mod
> + *	Return 0 if permission is granted.
> + * @delete_module:
> + *	Check permission before removing a module.
> + *	mod contains a pointer to the module being deleted.
	@mod
> + *	Return 0 if permission is granted.
> + * 

and the kernel-doc script generates a fair amount of warnings (no, i'm
not going to look into it, that script is in perl, and last time i
looked at it, it made my head hurt ;-)

finally, the hmtl is a bit broken...

"Check the permission before allocating space for a module. name contains
the module name. size contains the module size. Return 0 if permission
is granted."

this should really be:

Check the permission before allocating space for a module.
name contains the module name.
size contains the module size.
Return 0 if permission is granted.

again, probably an issue with the script.  greg mentioned it looked
better in docbook format anyway...

-chris

_______________________________________________
linux-security-module mailing list
linux-security-moduleat_private
http://mail.wirex.com/mailman/listinfo/linux-security-module