Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-12-26 04:42:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs-rst: parse-headers.pl: cleanup the documentation

Browse Source 
Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2016-11-30 08:00:20 -02:00 committed by Jonathan Corbet
parent 293fbd4fef
commit c339665666
2 changed files with 12 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Documentation/doc-guide/parse-headers.rst
View File

@ -18,13 +18,6 @@ about how to use it inside the Kernel tree.
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
****
@ -33,7 +26,6 @@ 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
********
@ -43,7 +35,6 @@ SYNOPSIS
Where <options> can be: --debug, --help or --man.
*******
OPTIONS
*******
@ -55,20 +46,17 @@ OPTIONS
\ **--help**\
\ **--usage**\
Prints a brief help message and exits.
\ **--man**\
\ **--help**\
Prints the manual page and exits.
Prints a more detailed help message and exits.
***********
DESCRIPTION
***********
@ -155,8 +143,6 @@ For both statements, \ **type**\ can be either one of the following:
********
EXAMPLES
********
@ -187,7 +173,6 @@ It will make the BAR1 and BAR2 enum symbols to cross reference the foo
symbol at the C domain.
****
BUGS
****
@ -195,7 +180,6 @@ BUGS
Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
*********
COPYRIGHT
*********

116
Documentation/sphinx/parse-headers.pl
View File

@ -10,8 +10,8 @@ my $man;
GetOptions(
"debug" => \$debug,
'help|?' => \$help,
man => \$man
'usage|?' => \$help,
'help' => \$man
) or pod2usage(2);
pod2usage(1) if $help;
@ -354,13 +354,13 @@ Where <options> can be: --debug, --help or --man.
Put the script in verbose mode, useful for debugging.
=item B<--help>
=item B<--usage>
Prints a brief help message and exits.
=item B<--man>
=item B<--help>
Prints the manual page and exits.
Prints a more detailed help message and exits.
=back
@ -379,109 +379,11 @@ 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: B<ignore> or B<replace>.
The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or
to replace the default references by a custom one.
The syntax for the ignore tag is:
=over 8
ignore B<type> B<name>
=back
The B<ignore> means that it won't generate cross references for a
B<name> symbol of type B<type>.
The syntax for the replace tag is:
=over 8
replace B<type> B<name> B<new_value>
=back
The B<replace> means that it will generate cross references for a
B<name> symbol of type B<type>, but, instead of using the default
replacement rule, it will use B<new_value>.
For both statements, B<type> can be either one of the following:
=over 8
=item B<ioctl>
The ignore or replace statement will apply to ioctl definitions like:
#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
=item B<define>
The ignore or replace statement will apply to any other #define found
at C_FILE.
=item B<typedef>
The ignore or replace statement will apply to typedef statements at C_FILE.
=item B<struct>
The ignore or replace statement will apply to the name of struct statements
at C_FILE.
=item B<enum>
The ignore or replace statement will apply to the name of enum statements
at C_FILE.
=item B<symbol>
The ignore or replace statement will apply to the name of enum statements
at C_FILE.
For replace statements, B<new_value> will automatically use :c:type:
references for B<typedef>, B<enum> and B<struct> types. It will use :ref:
for B<ioctl>, B<define> and B<symbol> types. The type of reference can
also be explicitly defined at the replace statement.
=back
=head1 EXAMPLES
ignore define _VIDEODEV2_H
=over 8
Ignore a #define _VIDEODEV2_H at the C_FILE.
=back
ignore symbol PRIVATE
=over 8
On a struct like:
enum foo { BAR1, BAR2, PRIVATE };
It won't generate cross-references for B<PRIVATE>.
=back
replace symbol BAR1 :c:type:`foo`
replace symbol BAR2 :c:type:`foo`
=over 8
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.
=back
Please read Documentation/doc-guide/parse-headers.rst at the Kernel's
tree for more details.
=head1 BUGS