From 2dde123b23ceba4b6d0d780b4e9fdcfb94621747 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 17 Nov 2016 08:32:35 -0200 Subject: [PATCH] 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 Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/parse-headers.rst | 26 +++++++++++++++++++++-- 1 file 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 ` 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