From fd7db68b9363a80d3c6f3b55e05ec56211ea6254 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 17 Jul 2016 19:24:02 -0600 Subject: docs: Get rid of some kernel-documentation warnings Sphinx wants to interpret all literal blocks as being in the chosen language and complains when an attempt to parse a block fails. kernel-documentation.rst has a few blocks that are not in C; make that explicit to shut down the associated warnings. Signed-off-by: Jonathan Corbet diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index 391decc..c4eb504 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, -- cgit v0.10.2 From e7ca311e376c81a51ce031c569f336bdadf5ea98 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 15 Jul 2016 10:19:30 +0200 Subject: kernel-doc: Fix up warning output While trying to make gpu docs warning free I stumbled over one output which wasn't following proper compiler error output standards. Fix it up for more quickfix awesomeness. Cc: Jonathan Corbet Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter Signed-off-by: Jonathan Corbet diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 932b3f3..7388e88 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2994,7 +2994,7 @@ sub process_file($) { } } elsif ($inline_doc_state == STATE_INLINE_NAME) { $inline_doc_state = STATE_INLINE_ERROR; - print STDERR "Warning(${file}:$.): "; + print STDERR "${file}:$.: warning: "; print STDERR "Incorrect use of kernel-doc format: $_"; ++$warnings; } -- cgit v0.10.2 From e6507a00fd08986ce003012a10af78cc7e47eee8 Mon Sep 17 00:00:00 2001 From: Jerome Marchand Date: Tue, 12 Jul 2016 12:05:59 +0200 Subject: Documentation: add watermark_scale_factor to the list of vm systcl file Commit 795ae7a0de6b ("mm: scale kswapd watermarks in proportion to memory") properly added the description of the new knob to Documentation/sysctl/vm.txt, but forgot to add it to the list of files in /proc/sys/vm. Let's fix that. Signed-off-by: Jerome Marchand Acked-by: Johannes Weiner Signed-off-by: Jonathan Corbet diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 720355c..95ccbe6 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 ============================================================== -- cgit v0.10.2 From 47d6d752b9e20dbe8a2acd22e887be81a6f39de9 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 19 Jul 2016 13:42:54 +0200 Subject: doc/sphinx: Enable keep_warnings Unfortunately warnings generated after parsing in sphinx can end up with entirely bogus files and line numbers as sources. Strangely for outright errors this is not a problem. Trying to convert warnings to errors also doesn't fix it. The only way to get useful output out of sphinx to be able to root cause the error seems to be enabling keep_warnings, which inserts a System Message into the actual output. Not pretty at all, but I don't really want to fix up core rst/sphinx code, and this gets the job done meanwhile. Cc: Markus Heiser Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter Signed-off-by: Jonathan Corbet diff --git a/Documentation/conf.py b/Documentation/conf.py index 792b633..49c242c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -125,7 +125,7 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +keep_warnings = True # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -- cgit v0.10.2 From 8ed292fe864e9ed7d335515e97590122a56d7cba Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 20 Jul 2016 16:43:41 -0600 Subject: docs: deprecate kernel-doc-nano-HOWTO.txt Now that the new Sphinx world order is taking over, the information in kernel-doc-nano-HOWTO.txt is outmoded. I hate to remove it altogether, since it's one of those files that people expect to find. But we can add a warning and fix all the other pointers to it. Reminded-by: Daniel Vetter Signed-off-by: Jonathan Corbet diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index cd077ca..cb9a6c6 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 9a70ddd..a096836 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 e3cb6a5..9a3ee77 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 78f69cd..062e3af 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/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle index bbb9d6a..1271779 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 风格 “// ...” 注释。 -- cgit v0.10.2 From f42ddca7bebcc069f470143434c119c96cd15bb5 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 20 Jul 2016 12:38:58 +0200 Subject: doc-rst: kernel-doc directive, fix state machine reporter Add a reporter replacement that assigns the correct source name and line number to a system message, as recorded in a ViewList. [1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com Signed-off-by: Markus Heiser Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index dedb24e..f6920c0 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"))] -- cgit v0.10.2 From 29310a50752de76314f51555b72044d11f6cba49 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 20 Jul 2016 16:56:21 -0600 Subject: Revert "doc/sphinx: Enable keep_warnings" This reverts commit 47d6d752b9e20dbe8a2acd22e887be81a6f39de9. Commit f42ddca7bebc (doc-rst: kernel-doc directive, fix state machine reporter) from Marcus Heiser provides a better fix, so this configuration change is no longer needed. diff --git a/Documentation/conf.py b/Documentation/conf.py index 49c242c..792b633 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -125,7 +125,7 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -keep_warnings = True +#keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -- cgit v0.10.2 From a88b1672d4ddf9895eb53e6980926d5e960dea8e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 11:46:36 -0300 Subject: doc-rst: kernel-doc: fix handling of address_space tags The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it: Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration. If the function has no return type: Error in declarator or parameters and qualifiers Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) --------^ If the function has a return type: Error in declarator or parameters and qualifiers If pointer to member declarator: Invalid definition: Expected '::' in pointer to member (function). [error at 37] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) -------------------------------------^ If declarator-id: Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) ------------------------------------------------------------------------------------------------------^ So, we have to remove it from the function prototype. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 7388e88..4f2e904 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1848,6 +1848,10 @@ sub output_function_rst(%) { } $count++; $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*\(([^\)]*)\)/) { # pointer-to-function print $1 . $parameter . ") (" . $2; -- cgit v0.10.2