GitHub-Mirror/Star64_linux
2
0
Fork 0
mirror of https://github.com/Fishwaldo/Star64_linux.git synced 2025-07-02 20:29:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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
Download patch file Download diff file Expand all files Collapse all files

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