Provide a man page for parse-headers.pl, describing how to use it. The documentation on ReST format was generated via pod2rst: http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> --- As requested, this patch adds documentation for parse-headers.pl. I opted to keep the ReST file as a separate one, instead of including it at Documentation/kernel-documentation.rst just for one reason: if something changes, I'll need to edit it only at the *.pl file, and re-run pod2rst. On a next patch, I'll likely edit its contents manually, to make it look better on ReST, but let's first agree on its contents ;) Btw, IMHO, we should actually place kernel-documentation on a subdir inside Documentation/ and break it into smaller pieces. This way, we can simply add new documents by editing an index.rst file, just like on the other documents. Documentation/index.rst | 1 + Documentation/parse-headers.rst | 183 ++++++++++++++++++++++++++++++++ Documentation/sphinx/parse-headers.pl | 190 +++++++++++++++++++++++++++++++--- 3 files changed, 362 insertions(+), 12 deletions(-) create mode 100644 Documentation/parse-headers.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index f6a3d4766495..54640ae33116 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,7 @@ Contents: admin-guide/index kernel-documentation + parse-headers process/index dev-tools/tools driver-api/index diff --git a/Documentation/parse-headers.rst b/Documentation/parse-headers.rst new file mode 100644 index 000000000000..0c7c6b0d0e84 --- /dev/null +++ b/Documentation/parse-headers.rst @@ -0,0 +1,183 @@ +================ +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**\ [--debug] <C_FILE> [<EXCEPTIONS_FILE>] + + +******* +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. + +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@xxxxxxxxxxxxxxxx> + + +********* +COPYRIGHT +********* + + +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>. + +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. + diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index c160a123be9a..3c9ba7ea1d3b 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -1,21 +1,24 @@ #!/usr/bin/perl use strict; use Text::Tabs; +use Getopt::Long; +use Pod::Usage; -my $debug = 0; +my $debug; +my $help; +my $man; -while ($ARGV[0] =~ m/^-(.*)/) { - my $cmd = shift @ARGV; - if ($cmd eq "--debug") { - require Data::Dumper; - $debug = 1; - next; - } - die "argument $cmd unknown"; -} +GetOptions( + "debug" => \$debug, + 'help|?' => \$help, + man => \$man +) or pod2usage(2); -if (scalar @ARGV < 2 || scalar @ARGV > 3) { - die "Usage:\n\t$0 <file in> [<exceptions file>]\n"; +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +if (scalar @ARGV < 1 || scalar @ARGV > 2) { + pod2usage(2); } my ($file_in, $file_exceptions) = @ARGV; @@ -28,6 +31,8 @@ my %enums; my %enum_symbols; my %structs; +require Data::Dumper if ($debug); + # # read the file and get identifiers # @@ -327,3 +332,164 @@ print "$title\n"; print "=" x length($title); print "\n\n.. parsed-literal::\n\n"; print $data; + +__END__ + +=head1 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. + +=head1 SYNOPSIS + +B<parse_headers.pl> [--debug] <C_FILE> [<EXCEPTIONS_FILE>] + +=head1 OPTIONS + +=over 8 + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 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. + +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: 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. + +=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 + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>. + +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. + +=cut -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
