Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c3396656 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

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



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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 293fbd4f

Documentation/doc-guide/parse-headers.rst

+3 −19
Original line number Diff line number Diff line
@@ -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**\



 Prints the manual page and exits.



\ **--help**\



 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

*********

Documentation/sphinx/parse-headers.pl

+9 −107
Original line number Diff line number Diff line
@@ -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 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.

The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or

to replace the default references by a custom one.



=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