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

[Paul Moore]

On Tue, Mar 9, 2021 at 9:40 AM Richard Haines
<richard_c_haines at 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?

-- 
paul moore
www.paul-moore.com