| Message ID | 20210309143953.142341-1-richard_c_haines@btinternet.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | LSM Documentation - Render lsm_hooks.h for kernel_docs | expand |
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?
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.
On Tue, 2021-04-13 at 14:01 -0500, Serge E. Hallyn wrote: > 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. Thanks for the comments, I'll rebuild on 5.12-rc7 and resubmit as a patch.
On Thu, Apr 15, 2021 at 9:54 AM Richard Haines <richard_c_haines@btinternet.com> wrote: > Thanks for the comments, I'll rebuild on 5.12-rc7 and resubmit as a > patch. Thanks Richard.