summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-23 07:55:59 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-23 07:55:59 -0300
commit7e5b7d1b3a8facd4dc1ddb5d9ec53c0687d13de7 (patch)
tree68bf4cf7fc44e0f8bf6e46116996fe7b969fda4e /Documentation
parente5208ed280685947b3892888df09285676aab100 (diff)
parenta88b1672d4ddf9895eb53e6980926d5e960dea8e (diff)
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
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/00-INDEX4
-rw-r--r--Documentation/CodingStyle2
-rw-r--r--Documentation/development-process/4.Coding2
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt3
-rw-r--r--Documentation/kernel-documentation.rst6
-rw-r--r--Documentation/sphinx/kernel-doc.py12
-rw-r--r--Documentation/sysctl/vm.txt1
-rw-r--r--Documentation/zh_CN/CodingStyle2
8 files changed, 24 insertions, 8 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index cd077ca0e1b8..cb9a6c6fa83b 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -255,10 +255,10 @@ kbuild/
- directory with info about the kernel build process.
kdump/
- 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
- listing of various WWW + books that document kernel internals.
+kernel-documentation.rst
+ - how to write and format reStructuredText kernel documentation
kernel-parameters.txt
- summary listing of command line / boot prompt args for the kernel.
kernel-per-CPU-kthreads.txt
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 9a70ddd16584..a096836723ca 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does
it.
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.
Linux style for comments is the C89 "/* ... */" style.
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding
index e3cb6a56653a..9a3ee77cefb1 100644
--- a/Documentation/development-process/4.Coding
+++ b/Documentation/development-process/4.Coding
@@ -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
beginning kernel developers. The format of these comments, along with some
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
note that, often, comments are most notable by their absence. Once again,
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 78f69cdc9b3f..062e3af271b7 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -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
=====================
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 391decc66a18..c4eb5049da39 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -366,6 +366,8 @@ Domain`_ references.
Cross-referencing from reStructuredText
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. highlight:: none
+
To cross-reference the functions and types defined in the kernel-doc comments
from reStructuredText documents, please use the `Sphinx C Domain`_
references. For example::
@@ -388,6 +390,8 @@ For further details, please refer to the `Sphinx C Domain`_ documentation.
Function documentation
----------------------
+.. highlight:: c
+
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
----------------------------
+.. highlight:: none
+
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
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py
index dedb24e3bb7a..f6920c0af6ee 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -37,6 +37,7 @@ from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives
from sphinx.util.compat import Directive
+from sphinx.ext.autodoc import AutodocReporter
class KernelDocDirective(Directive):
"""Extract kernel-doc comments from the specified file"""
@@ -117,12 +118,17 @@ class KernelDocDirective(Directive):
lineoffset += 1
node = nodes.section()
- node.document = self.state.document
- self.state.nested_parse(result, self.content_offset, node)
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ 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
- except Exception as e:
+ except Exception as e: # pylint: disable=W0703
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
(" ".join(cmd), str(e)))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 720355cbdf45..95ccbe6d79ce 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm:
- swappiness
- user_reserve_kbytes
- vfs_cache_pressure
+- watermark_scale_factor
- zone_reclaim_mode
==============================================================
diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle
index bbb9d6ae05ca..12717791baac 100644
--- a/Documentation/zh_CN/CodingStyle
+++ b/Documentation/zh_CN/CodingStyle
@@ -399,7 +399,7 @@ C是一个简朴的语言,你的命名也应该这样。和 Modula-2 和 Pasca
些事情的原因。
当注释内核API函数时,请使用 kernel-doc 格式。请看
-Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc 以获得详细信息。
+Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。