diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-11-17 13:32:34 +0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2016-11-19 20:22:08 +0300 |
commit | 327f5a754ab14aa9dc20e9c31cf776680b1d9a4d (patch) | |
tree | 6b576609151d5d8cb6d4c18cf9aca12cdce3d3d5 /Documentation/doc-guide | |
parent | 1dc4bbf0b268246f6202c761016735933b6f0b99 (diff) | |
download | linux-327f5a754ab14aa9dc20e9c31cf776680b1d9a4d.tar.xz |
parse-headers.pl: add documentation for this script
Provide a man page for parse-headers.pl, describing
how to use it.
The documentation on ReST format was generated via pod2rst:
http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
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/index.rst | 1 | ||||
-rw-r--r-- | Documentation/doc-guide/parse-headers.rst | 186 |
2 files changed, 187 insertions, 0 deletions
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst index 695b7b6cf6ed..6fff4024606e 100644 --- a/Documentation/doc-guide/index.rst +++ b/Documentation/doc-guide/index.rst @@ -9,6 +9,7 @@ How to write kernel documentation sphinx.rst kernel-doc.rst + parse-headers.rst docbook.rst .. only:: subproject and html diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..a1867d757ff4 --- /dev/null +++ b/Documentation/doc-guide/parse-headers.rst @@ -0,0 +1,186 @@ +================ +parse_headers.pl +================ + +**** +NAME +**** + + +parse_headers.pl - parse a C file, in order to identify functions, structs, +enums and defines and create cross-references to a Sphinx book. + + +******** +SYNOPSIS +******** + + +\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] + +Where <options> can be: --debug, --help or --man. + + +******* +OPTIONS +******* + + + +\ **--debug**\ + + Put the script in verbose mode, useful for debugging. + + + +\ **--help**\ + + Prints a brief help message and exits. + + + +\ **--man**\ + + Prints the manual page and exits. + + + + +*********** +DESCRIPTION +*********** + + +Convert a C header or source file (C_FILE), into a ReStructured Text +included via ..parsed-literal block with cross-references for the +documentation files that describe the API. It accepts an optional +EXCEPTIONS_FILE with describes what elements will be either ignored or +be pointed to a non-default reference. + +The output is written at the (OUT_FILE). + +It is capable of identifying defines, functions, structs, typedefs, +enums and enum symbols and create cross-references for all of them. +It is also capable of distinguish #define used for specifying a Linux +ioctl. + +The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . + +The syntax for the ignore tag is: + + +ignore \ **type**\ \ **name**\ + +The \ **ignore**\ means that it won't generate cross references for a +\ **name**\ symbol of type \ **type**\ . + +The syntax for the replace tag is: + + +replace \ **type**\ \ **name**\ \ **new_value**\ + +The \ **replace**\ means that it will generate cross references for a +\ **name**\ symbol of type \ **type**\ , but, instead of using the default +replacement rule, it will use \ **new_value**\ . + +For both statements, \ **type**\ can be either one of the following: + + +\ **ioctl**\ + + The ignore or replace statement will apply to ioctl definitions like: + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + The ignore or replace statement will apply to any other #define found + at C_FILE. + + + +\ **typedef**\ + + The ignore or replace statement will apply to typedef statements at C_FILE. + + + +\ **struct**\ + + The ignore or replace statement will apply to the name of struct statements + at C_FILE. + + + +\ **enum**\ + + The ignore or replace statement will apply to the name of enum statements + at C_FILE. + + + +\ **symbol**\ + + The ignore or replace statement will apply to the name of enum statements + at C_FILE. + + For replace statements, \ **new_value**\ will automatically use :c:type: + references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: + for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can + also be explicitly defined at the replace statement. + + + + +******** +EXAMPLES +******** + + +ignore define _VIDEODEV2_H + + +Ignore a #define _VIDEODEV2_H at the C_FILE. + +ignore symbol PRIVATE + + +On a struct like: + +enum foo { BAR1, BAR2, PRIVATE }; + +It won't generate cross-references for \ **PRIVATE**\ . + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +On a struct like: + +enum foo { BAR1, BAR2, PRIVATE }; + +It will make the BAR1 and BAR2 enum symbols to cross reference the foo +symbol at the C domain. + + +**** +BUGS +**** + + +Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com> + + +********* +COPYRIGHT +********* + + +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. + +License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. |