Documentation/doc-guide/parse-headers.rst
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/userspace-api/media/Makefile for an example
about how to use it inside the Kernel tree.
.. _parse_headers:
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 --usage.
OPTIONS
\ --debug\
Put the script in verbose mode, useful for debugging.
\ --usage\
Prints a brief help message and exits.
\ --help\
Prints a more detailed help message 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 value 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 [email protected]
COPYRIGHT
Copyright (c) 2016 by Mauro Carvalho Chehab [email protected].
License GPLv2: GNU GPL version 2 https://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.