• Matthew Wilcox's avatar
    Restructure kernel-doc.rst · 46347502
    Matthew Wilcox authored
    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: default avatarMatthew Wilcox <mawilcox@microsoft.com>
    Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Last commit
Last update
conf.py Loading commit data...
hello.dot Loading commit data...
index.rst Loading commit data...
kernel-doc.rst Loading commit data...
parse-headers.rst Loading commit data...
sphinx.rst Loading commit data...
svg_image.svg Loading commit data...