Commit 7e5b7d1b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

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
parents e5208ed2 a88b1672
...@@ -255,10 +255,10 @@ kbuild/ ...@@ -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 ...@@ -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 ...@@ -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,
......
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. ...@@ -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. ...@@ -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] ...@@ -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 ...@@ -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): ...@@ -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: ...@@ -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 ...@@ -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(%) { ...@@ -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($) { ...@@ -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;
} }
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment