Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-next
* 'docs-next' of git://git.lwn.net/linux: doc-rst: kernel-doc: fix handling of address_space tags Revert "doc/sphinx: Enable keep_warnings" doc-rst: kernel-doc directive, fix state machine reporter docs: deprecate kernel-doc-nano-HOWTO.txt doc/sphinx: Enable keep_warnings Documentation: add watermark_scale_factor to the list of vm systcl file kernel-doc: Fix up warning output docs: Get rid of some kernel-documentation warnings
This commit is contained in:
commit
7e5b7d1b3a
9 changed files with 29 additions and 9 deletions
|
@ -255,10 +255,10 @@ kbuild/
|
||||||
- directory with info about the kernel build process.
|
- directory with info about the kernel build process.
|
||||||
kdump/
|
kdump/
|
||||||
- directory with mini HowTo on getting the crash dump code to work.
|
- directory with mini HowTo on getting the crash dump code to work.
|
||||||
kernel-doc-nano-HOWTO.txt
|
|
||||||
- mini HowTo on generation and location of kernel documentation files.
|
|
||||||
kernel-docs.txt
|
kernel-docs.txt
|
||||||
- listing of various WWW + books that document kernel internals.
|
- listing of various WWW + books that document kernel internals.
|
||||||
|
kernel-documentation.rst
|
||||||
|
- how to write and format reStructuredText kernel documentation
|
||||||
kernel-parameters.txt
|
kernel-parameters.txt
|
||||||
- summary listing of command line / boot prompt args for the kernel.
|
- summary listing of command line / boot prompt args for the kernel.
|
||||||
kernel-per-CPU-kthreads.txt
|
kernel-per-CPU-kthreads.txt
|
||||||
|
|
|
@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does
|
||||||
it.
|
it.
|
||||||
|
|
||||||
When commenting the kernel API functions, please use the kernel-doc format.
|
When commenting the kernel API functions, please use the kernel-doc format.
|
||||||
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
|
See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
Linux style for comments is the C89 "/* ... */" style.
|
Linux style for comments is the C89 "/* ... */" style.
|
||||||
|
|
|
@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc
|
||||||
comments for the future; indeed, this can be a useful activity for
|
comments for the future; indeed, this can be a useful activity for
|
||||||
beginning kernel developers. The format of these comments, along with some
|
beginning kernel developers. The format of these comments, along with some
|
||||||
information on how to create kerneldoc templates can be found in the file
|
information on how to create kerneldoc templates can be found in the file
|
||||||
Documentation/kernel-doc-nano-HOWTO.txt.
|
Documentation/kernel-documentation.rst.
|
||||||
|
|
||||||
Anybody who reads through a significant amount of existing kernel code will
|
Anybody who reads through a significant amount of existing kernel code will
|
||||||
note that, often, comments are most notable by their absence. Once again,
|
note that, often, comments are most notable by their absence. Once again,
|
||||||
|
|
|
@ -1,3 +1,6 @@
|
||||||
|
NOTE: this document is outdated and will eventually be removed. See
|
||||||
|
Documentation/kernel-documentation.rst for current information.
|
||||||
|
|
||||||
kernel-doc nano-HOWTO
|
kernel-doc nano-HOWTO
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
|
|
|
@ -366,6 +366,8 @@ Domain`_ references.
|
||||||
Cross-referencing from reStructuredText
|
Cross-referencing from reStructuredText
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. highlight:: none
|
||||||
|
|
||||||
To cross-reference the functions and types defined in the kernel-doc comments
|
To cross-reference the functions and types defined in the kernel-doc comments
|
||||||
from reStructuredText documents, please use the `Sphinx C Domain`_
|
from reStructuredText documents, please use the `Sphinx C Domain`_
|
||||||
references. For example::
|
references. For example::
|
||||||
|
@ -388,6 +390,8 @@ For further details, please refer to the `Sphinx C Domain`_ documentation.
|
||||||
Function documentation
|
Function documentation
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
.. highlight:: c
|
||||||
|
|
||||||
The general format of a function and function-like macro kernel-doc comment is::
|
The general format of a function and function-like macro kernel-doc comment is::
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -568,6 +572,8 @@ DocBook XML [DEPRECATED]
|
||||||
Converting DocBook to Sphinx
|
Converting DocBook to Sphinx
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
|
.. highlight:: none
|
||||||
|
|
||||||
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
|
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
|
||||||
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
|
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
|
||||||
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
|
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
|
||||||
|
|
|
@ -37,6 +37,7 @@ from docutils import nodes, statemachine
|
||||||
from docutils.statemachine import ViewList
|
from docutils.statemachine import ViewList
|
||||||
from docutils.parsers.rst import directives
|
from docutils.parsers.rst import directives
|
||||||
from sphinx.util.compat import Directive
|
from sphinx.util.compat import Directive
|
||||||
|
from sphinx.ext.autodoc import AutodocReporter
|
||||||
|
|
||||||
class KernelDocDirective(Directive):
|
class KernelDocDirective(Directive):
|
||||||
"""Extract kernel-doc comments from the specified file"""
|
"""Extract kernel-doc comments from the specified file"""
|
||||||
|
@ -117,12 +118,17 @@ class KernelDocDirective(Directive):
|
||||||
lineoffset += 1
|
lineoffset += 1
|
||||||
|
|
||||||
node = nodes.section()
|
node = nodes.section()
|
||||||
node.document = self.state.document
|
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
|
||||||
self.state.nested_parse(result, self.content_offset, node)
|
self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
|
||||||
|
self.state.memo.title_styles, self.state.memo.section_level = [], 0
|
||||||
|
try:
|
||||||
|
self.state.nested_parse(result, 0, node, match_titles=1)
|
||||||
|
finally:
|
||||||
|
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
|
||||||
|
|
||||||
return node.children
|
return node.children
|
||||||
|
|
||||||
except Exception as e:
|
except Exception as e: # pylint: disable=W0703
|
||||||
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
|
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
|
||||||
(" ".join(cmd), str(e)))
|
(" ".join(cmd), str(e)))
|
||||||
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
|
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
|
||||||
|
|
|
@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm:
|
||||||
- swappiness
|
- swappiness
|
||||||
- user_reserve_kbytes
|
- user_reserve_kbytes
|
||||||
- vfs_cache_pressure
|
- vfs_cache_pressure
|
||||||
|
- watermark_scale_factor
|
||||||
- zone_reclaim_mode
|
- zone_reclaim_mode
|
||||||
|
|
||||||
==============================================================
|
==============================================================
|
||||||
|
|
|
@ -399,7 +399,7 @@ C是一个简朴的语言,你的命名也应该这样。和 Modula-2 和 Pasca
|
||||||
些事情的原因。
|
些事情的原因。
|
||||||
|
|
||||||
当注释内核API函数时,请使用 kernel-doc 格式。请看
|
当注释内核API函数时,请使用 kernel-doc 格式。请看
|
||||||
Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc 以获得详细信息。
|
Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
|
||||||
|
|
||||||
Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
|
Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
|
||||||
|
|
||||||
|
|
|
@ -1848,6 +1848,10 @@ sub output_function_rst(%) {
|
||||||
}
|
}
|
||||||
$count++;
|
$count++;
|
||||||
$type = $args{'parametertypes'}{$parameter};
|
$type = $args{'parametertypes'}{$parameter};
|
||||||
|
|
||||||
|
# RST doesn't like address_space tags at function prototypes
|
||||||
|
$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
|
||||||
|
|
||||||
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
||||||
# pointer-to-function
|
# pointer-to-function
|
||||||
print $1 . $parameter . ") (" . $2;
|
print $1 . $parameter . ") (" . $2;
|
||||||
|
@ -2994,7 +2998,7 @@ sub process_file($) {
|
||||||
}
|
}
|
||||||
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
|
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
|
||||||
$inline_doc_state = STATE_INLINE_ERROR;
|
$inline_doc_state = STATE_INLINE_ERROR;
|
||||||
print STDERR "Warning(${file}:$.): ";
|
print STDERR "${file}:$.: warning: ";
|
||||||
print STDERR "Incorrect use of kernel-doc format: $_";
|
print STDERR "Incorrect use of kernel-doc format: $_";
|
||||||
++$warnings;
|
++$warnings;
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in a new issue