46347502b0
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>
Linux kernel ============ This file was moved to Documentation/admin-guide/README.rst Please notice that there are several guides for kernel developers and users. These guides can be rendered in a number of formats, like HTML and PDF. In order to build the documentation, use ``make htmldocs`` or ``make pdfdocs``. There are various text files in the Documentation/ subdirectory, several of them using the Restructured Text markup notation. See Documentation/00-INDEX for a list of what is contained in each file. Please read the Documentation/process/changes.rst file, as it contains the requirements for building and running the kernel, and information about the problems which may result by upgrading your kernel.