From c3396656666c2c98db306dc91c480d9fbde35cc9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 30 Nov 2016 08:00:20 -0200 Subject: [PATCH] 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: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/parse-headers.rst | 22 +--- Documentation/sphinx/parse-headers.pl | 116 ++-------------------- 2 files changed, 12 insertions(+), 126 deletions(-) diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 615e25ec64bb..96a0423d5dba 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -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 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 -********* COPYRIGHT ********* diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 20dbdf55c71e..a958d8b5e99d 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -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 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 or B. +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 B - -=back - -The B means that it won't generate cross references for a -B symbol of type B. - -The syntax for the replace tag is: - -=over 8 - -replace B B B - -=back - -The B means that it will generate cross references for a -B symbol of type B, but, instead of using the default -replacement rule, it will use B. - -For both statements, B can be either one of the following: - -=over 8 - -=item B - -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 - -The ignore or replace statement will apply to any other #define found -at C_FILE. - -=item B - -The ignore or replace statement will apply to typedef statements at C_FILE. - -=item B - -The ignore or replace statement will apply to the name of struct statements -at C_FILE. - -=item B - -The ignore or replace statement will apply to the name of enum statements -at C_FILE. - -=item B - -The ignore or replace statement will apply to the name of enum statements -at C_FILE. - - -For replace statements, B will automatically use :c:type: -references for B, B and B types. It will use :ref: -for B, B and B 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. - -=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