From 327f5a754ab14aa9dc20e9c31cf776680b1d9a4d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 17 Nov 2016 08:32:34 -0200 Subject: parse-headers.pl: add documentation for this script 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 Signed-off-by: Jonathan Corbet --- Documentation/sphinx/parse-headers.pl | 193 +++++++++++++++++++++++++++++++--- 1 file changed, 180 insertions(+), 13 deletions(-) (limited to 'Documentation/sphinx/parse-headers.pl') diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index db0186a7618f..20dbdf55c71e 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -1,22 +1,22 @@ #!/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 []\n"; -} +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; +pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3); my ($file_in, $file_out, $file_exceptions) = @ARGV; @@ -28,6 +28,8 @@ my %enums; my %enum_symbols; my %structs; +require Data::Dumper if ($debug); + # # read the file and get identifiers # @@ -330,3 +332,168 @@ print OUT "=" x length($title); print OUT "\n\n.. parsed-literal::\n\n"; print OUT $data; close OUT; + +__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 [] [] + +Where can be: --debug, --help or --man. + +=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. + +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: B or B. + +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 + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab . + +License GPLv2: GNU GPL version 2 . + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut -- cgit