summaryrefslogtreecommitdiff
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-11-17 08:32:35 -0200
committerJonathan Corbet <corbet@lwn.net>2016-11-19 10:22:15 -0700
commit2dde123b23ceba4b6d0d780b4e9fdcfb94621747 (patch)
treea4043ad1aacb1c99d97fa497d643ef3938dd18f3 /Documentation/doc-guide
parent327f5a754ab14aa9dc20e9c31cf776680b1d9a4d (diff)
parse-headers.rst: add an introduction to the man page
The pod2rst tool generated a man page for parse-headers.pl script, but it is better to put it into some context. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/parse-headers.rst26
1 files changed, 24 insertions, 2 deletions
diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
index a1867d757ff4..615e25ec64bb 100644
--- a/Documentation/doc-guide/parse-headers.rst
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -1,6 +1,28 @@
-================
+===========================
+Including uAPI header files
+===========================
+
+Sometimes, it is useful to include header files and C example codes in
+order to describe the userspace API and to generate cross-references
+between the code and the documentation. Adding cross-references for
+userspace API files has an additional vantage: Sphinx will generate warnings
+if a symbol is not found at the documentation. That helps to keep the
+uAPI documentation in sync with the Kernel changes.
+The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such
+cross-references. It has to be called via Makefile, while building the
+documentation. Please see ``Documentation/media/Makefile`` for an example
+about how to use it inside the Kernel tree.
+
+.. _parse_headers:
+
parse_headers.pl
-================
+^^^^^^^^^^^^^^^^
+
+.. NOTE: the man pages below were generated using pod2rst tool:
+.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
+.. If you need to change anything below this point, please do the changes
+.. at parse-headers.pl directly, re-run the script and paste the output of
+.. the script here.
****
NAME