Re: [RFC PATCH 0/3] LSM Documentation - Render lsm_hooks.h for kernel_docs

["Serge E. Hallyn" <serge@hallyn.com>]

On Wed, Apr 07, 2021 at 09:42:01PM -0400, Paul Moore wrote:
> On Tue, Mar 9, 2021 at 9:40 AM Richard Haines
> <richard_c_haines@btinternet.com> wrote:
> >
> > This patch series updates the LSM hook text defined in the comments
> > section of inlcude/linux/lsm_hooks.h. This enables the hook functions to
> > be rendered in kernel_docs html or pdf format.
> >
> > Note that no text has been changed in lsm_hooks.h, only formatting
> > to render the text.
> >
> > To get the correct rendering some lines have exceeded checkpatch limits and
> > therefore has a moan. The function statements seem to need being a
> > continuous line. The others can be split, but decided not to.
> > Any better ideas ??
> >
> > The hook functions render in HTML ok, however in PDF format the only issue
> > is that the long function definitions do not wrap and therefore truncated.
> > Check the 'int sb_mount(const char *dev_name' entry in:
> > Documentation/output/pdf/security.pdf
> >
> > For reference two hooks have been marked as deprecated: sb_copy_data() and
> > sb_parse_opts_str()
> >
> > Tested using 'make pdfdocs' and 'make htmldocs'
> >
> > Richard Haines (3):
> >   Documentation/security: Update LSM security hook text
> >   include/linux: Update LSM hook text part1
> >   include/linux: Update LSM hook text part2
> >
> >  Documentation/security/lsm-development.rst |    5 +-
> >  include/linux/lsm_hooks.h                  | 2365 +++++++++++---------
> >  2 files changed, 1364 insertions(+), 1006 deletions(-)
> 
> I haven't yet pulled this patchset to generate the HTML/PDF docs, but
> just looking at the comments themselves it looks reasonable to me ...
> and I say this as being perhaps one of the stricter folks under
> security/ when it comes to 80 character line lengths :)  In my
> opinion, the benefit of being able to render the docs nicely outweigh
> the pain of scrolling horizontally in my editor.  Thanks for doing
> this Richard.
> 
> Does anyone else have any thoughts on these changes?

No objection from me.