[mirror_ubuntu-zesty-kernel.git] / Documentation / doc-guide / parse-headers.rst

================
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.
Commit	Line	Data
327f5a75 MCC	1	================
	2	parse_headers.pl
	3	================
	4
	5	****
	6	NAME
	7	****
	8
	9
	10	parse_headers.pl - parse a C file, in order to identify functions, structs,
	11	enums and defines and create cross-references to a Sphinx book.
	12
	13
	14	********
	15	SYNOPSIS
	16	********
	17
	18
	19	\ parse_headers.pl\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
	20
	21	Where <options> can be: --debug, --help or --man.
	22
	23
	24	*******
	25	OPTIONS
	26	*******
	27
	28
	29
	30	\ --debug\
	31
	32	Put the script in verbose mode, useful for debugging.
	33
	34
	35
	36	\ --help\
	37
	38	Prints a brief help message and exits.
	39
	40
	41
	42	\ --man\
	43
	44	Prints the manual page and exits.
	45
	46
	47
	48
	49	***********
	50	DESCRIPTION
	51	***********
	52
	53
	54	Convert a C header or source file (C_FILE), into a ReStructured Text
	55	included via ..parsed-literal block with cross-references for the
	56	documentation files that describe the API. It accepts an optional
	57	EXCEPTIONS_FILE with describes what elements will be either ignored or
	58	be pointed to a non-default reference.
	59
	60	The output is written at the (OUT_FILE).
	61
	62	It is capable of identifying defines, functions, structs, typedefs,
	63	enums and enum symbols and create cross-references for all of them.
	64	It is also capable of distinguish #define used for specifying a Linux
65	ioctl.
66
67	The EXCEPTIONS_FILE contain two types of statements: \ ignore\ or \ replace\ .
68
69	The syntax for the ignore tag is:
70
71
72	ignore \ type\ \ name\
73
74	The \ ignore\ means that it won't generate cross references for a
75	\ name\ symbol of type \ type\ .
76
77	The syntax for the replace tag is:
78
79
80	replace \ type\ \ name\ \ new_value\
81
82	The \ replace\ means that it will generate cross references for a
83	\ name\ symbol of type \ type\ , but, instead of using the default
84	replacement rule, it will use \ new_value\ .
85
86	For both statements, \ type\ can be either one of the following:
87
88
89	\ ioctl\
90
91	The ignore or replace statement will apply to ioctl definitions like:
92
93	#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
94
95
96
97	\ define\
98
99	The ignore or replace statement will apply to any other #define found
100	at C_FILE.
101
102
103
104	\ typedef\
105
106	The ignore or replace statement will apply to typedef statements at C_FILE.
107
108
109
110	\ struct\
111
112	The ignore or replace statement will apply to the name of struct statements
113	at C_FILE.
114
115
116
117	\ enum\
118
119	The ignore or replace statement will apply to the name of enum statements
120	at C_FILE.
121
122
123
124	\ symbol\
125
126	The ignore or replace statement will apply to the name of enum statements
127	at C_FILE.
128
129	For replace statements, \ new_value\ will automatically use :c:type:
130	references for \ typedef\ , \ enum\ and \ struct\ types. It will use :ref:
131	for \ ioctl\ , \ define\ and \ symbol\ types. The type of reference can
132	also be explicitly defined at the replace statement.
133
134
135
136
137	********
138	EXAMPLES
139	********
140
141
142	ignore define _VIDEODEV2_H
143
144
145	Ignore a #define _VIDEODEV2_H at the C_FILE.
146
147	ignore symbol PRIVATE
148
149
150	On a struct like:
151
152	enum foo { BAR1, BAR2, PRIVATE };
153
154	It won't generate cross-references for \ PRIVATE\ .
155
156	replace symbol BAR1 :c:type:\`foo\`
157	replace symbol BAR2 :c:type:\`foo\`
158
159
160	On a struct like:
161
162	enum foo { BAR1, BAR2, PRIVATE };
163
164	It will make the BAR1 and BAR2 enum symbols to cross reference the foo
165	symbol at the C domain.
166
167
168	****
169	BUGS
170	****
171
172
173	Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
174
175
176	*********
177	COPYRIGHT
178	*********
179
180
181	Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
182
183	License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
184
185	This is free software: you are free to change and redistribute it.
186	There is NO WARRANTY, to the extent permitted by law.