Restructure kernel-doc.rst
I found the layout confusing with multiple introductions to what
kernel-doc is and how to use it.
I made the following changes:
- Moved the 'Including kernel-doc comments' section to the end of
the document -- we should explain what it *is* before we explain
how to integrate it.
- Moved the 'Recommendations' subsection to the top. We want people
to know what to document before telling them how to do it.
- Rewrite the 'Writing kernel-doc comments' section, integrating
the 'Recommendations' subsection and a paragraph from 'How to format
kernel-doc comments'.
- Remove the paragraph about the kernel-doc script; we're supposed to
be teaching people how to use punctuation to write pretty documentation,
not documenting the build tooling.
- Split the 'Parameters and member arguments' section into 'Function
parameters' and 'Members'. Structure members are not commonly
referred to as arguments.
- Integrate the 'private:' and 'public:' tag descriptions into the
'Members' section.
- Move the 'In-line member documentation comments' subsection up to be
with the 'Members' section.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
1 file changed