mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
4d535c7038
This makes a number of small changes to how the internal documentation is generated and what can be documented. Header files are now permitted to contain internal documentation. This works in the same wasy as .c files. Also documentation can be added for structs as well as functions. This commit also adds documentation to some header files and structs, and fixes a few places which contained broken header documentation.
312 lines
8.6 KiB
Perl
Executable File
312 lines
8.6 KiB
Perl
Executable File
#!/usr/bin/env perl
|
|
# Copyright (C) 2016 Red Hat Inc.
|
|
#
|
|
# This program is free software; you can redistribute it and/or modify
|
|
# it under the terms of the GNU General Public License as published by
|
|
# the Free Software Foundation; either version 2 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program; if not, write to the Free Software
|
|
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
|
|
use warnings;
|
|
use strict;
|
|
|
|
use Pod::Usage;
|
|
use Getopt::Long;
|
|
|
|
=head1 NAME
|
|
|
|
make-internal-documentation.pl - Generate internal documentation from C files
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
make-internal-documentation.pl --output internal-documentation.pod
|
|
[C source files ...]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
C<make-internal-documentation.pl> is a script that generates
|
|
L<guestfs-hacking(1)/INTERNAL DOCUMENTATION>.
|
|
|
|
You must specify the name of the output file using the I<-o> or
|
|
I<--output> option, and a list of the C source files in the project.
|
|
|
|
=head2 Function and struct documentation
|
|
|
|
Internal documentation is added to the C source files using special
|
|
comments which appear before function or struct definitions:
|
|
|
|
/**
|
|
* Returns true if C<foo> equals C<bar>.
|
|
*/
|
|
bool
|
|
is_equal (const char *foo, const char *bar)
|
|
{
|
|
...
|
|
|
|
/**
|
|
* Struct used to store C<bar>s.
|
|
*/
|
|
struct foo_bar {
|
|
...
|
|
|
|
The comment is written in POD format (see L<perlpod(1)>). It may be
|
|
on several lines, and be split into paragraphs using blank lines.
|
|
|
|
The thing being documented should appear immediately after the special
|
|
comment, and is also copied into the documentation.
|
|
|
|
=head2 File documentation
|
|
|
|
In addition, each C file may have a special comment at the top of the
|
|
file (before any C<#include> lines) which outlines what the file does.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=cut
|
|
|
|
my $help;
|
|
|
|
=item B<--help>
|
|
|
|
Display brief help.
|
|
|
|
=cut
|
|
|
|
my $man;
|
|
|
|
=item B<--man>
|
|
|
|
Display full documentation (man page).
|
|
|
|
=cut
|
|
|
|
my $output;
|
|
|
|
=item B<-o output.pod>
|
|
|
|
=item B<--output output.pod>
|
|
|
|
Set the name of the output file (required).
|
|
|
|
=cut
|
|
|
|
my $srcdir = ".";
|
|
|
|
=item B<--srcdir top_srcdir>
|
|
|
|
Path to the top source directory. Input filenames are
|
|
located relative to this path.
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
# Clean up the program name.
|
|
my $progname = $0;
|
|
$progname =~ s{.*/}{};
|
|
|
|
# Parse options.
|
|
GetOptions ("help|?" => \$help,
|
|
"man" => \$man,
|
|
"output=s" => \$output,
|
|
"srcdir=s" => \$srcdir,
|
|
) or pod2usage (2);
|
|
pod2usage (-exitval => 0) if $help;
|
|
pod2usage (-exitval => 0, -verbose => 2) if $man;
|
|
|
|
die "$progname: missing -o/--output parameter\n" unless defined $output;
|
|
|
|
die "$progname: missing argument: make-internal-documentation [C source files ...]\n" unless @ARGV >= 1;
|
|
|
|
# Only consider input files which
|
|
# - are C source or header files
|
|
# - exist
|
|
# - contain /** comments.
|
|
|
|
my @inputs = ();
|
|
my $input;
|
|
my $path;
|
|
foreach $input (@ARGV) {
|
|
if ($input =~ /\.[ch]$/) {
|
|
$path = "$srcdir/$input";
|
|
if (-r $path) {
|
|
my @cmd = ("grep", "-q", "^/\\*\\*", $path);
|
|
if (system (@cmd) == 0) {
|
|
push @inputs, $input
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
# Sort the input files into directory sections. Put the 'src'
|
|
# directory first, and the rest follow in alphabetical order.
|
|
my %dirs = ();
|
|
foreach $input (@inputs) {
|
|
die unless $input =~ m{^(.*)/([^/]+)$};
|
|
$dirs{$1} = [] unless exists $dirs{$1};
|
|
push @{$dirs{$1}}, $2
|
|
}
|
|
sub src_first {
|
|
if ($a eq "src" && $b eq "src") { return 0 }
|
|
elsif ($a eq "src") { return -1 }
|
|
elsif ($b eq "src") { return 1 }
|
|
else { return $a cmp $b }
|
|
}
|
|
my @dirs = sort src_first (keys %dirs);
|
|
|
|
open OUTPUT, ">$output" or die "$progname: $output: $!";
|
|
|
|
my $dir;
|
|
foreach $dir (@dirs) {
|
|
print OUTPUT ("=head2 Subdirectory F<$dir>\n\n");
|
|
|
|
my $file;
|
|
foreach $file (sort @{$dirs{$dir}}) {
|
|
my $input = "$dir/$file";
|
|
$path = "$srcdir/$input";
|
|
|
|
print OUTPUT ("=head3 File F<$input>\n\n");
|
|
|
|
open INPUT, $path or die "$progname: $input: $!";
|
|
|
|
# A single special comment seen before any #includes can be
|
|
# used to outline the purpose of the source file.
|
|
my $seen_includes = 0;
|
|
my $lineno = 0;
|
|
|
|
while (<INPUT>) {
|
|
chomp;
|
|
$lineno++;
|
|
$seen_includes = 1 if /^#include/;
|
|
|
|
if (m{^/\*\*$}) {
|
|
# Found a special comment. Read the whole comment.
|
|
my @comment = ();
|
|
my $found_end = 0;
|
|
my $start_lineno = $lineno;
|
|
while (<INPUT>) {
|
|
chomp;
|
|
$lineno++;
|
|
|
|
if (m{^ \*/$}) {
|
|
$found_end = 1;
|
|
last;
|
|
}
|
|
elsif (m{^ \* (.*)}) {
|
|
push @comment, $1;
|
|
}
|
|
elsif (m{^ \*$}) {
|
|
push @comment, "";
|
|
}
|
|
else {
|
|
die "$progname: $input: $lineno: special comment with incorrect format\n";
|
|
}
|
|
}
|
|
die "$progname: $input: $start_lineno: unterminated special comment"
|
|
unless $found_end;
|
|
|
|
unless ($seen_includes) {
|
|
# If we've not seen the includes yet, then this is
|
|
# the top of file special comment, so we just
|
|
# write it out.
|
|
print OUTPUT join("\n", @comment), "\n";
|
|
print OUTPUT "\n";
|
|
}
|
|
else {
|
|
# Otherwise it's a function or struct description,
|
|
# so now we need to read in the definition.
|
|
my @defn = ();
|
|
my $thing = undef;
|
|
my $end = undef;
|
|
my $name = undef;
|
|
$found_end = 0;
|
|
$start_lineno = $lineno;
|
|
while (<INPUT>) {
|
|
chomp;
|
|
$lineno++;
|
|
|
|
if (defined $end) {
|
|
if ($_ eq $end) {
|
|
$found_end = 1;
|
|
last;
|
|
}
|
|
else {
|
|
push @defn, $_;
|
|
}
|
|
}
|
|
else {
|
|
# First line tells us if this is a struct
|
|
# or function.
|
|
if (/^struct ([\w_]+) \{$/) {
|
|
$thing = "Structure";
|
|
$name = $1;
|
|
$end = "};";
|
|
}
|
|
else {
|
|
$thing = "Function";
|
|
$end = "{";
|
|
}
|
|
push @defn, $_;
|
|
}
|
|
}
|
|
|
|
die "$progname: $input: $start_lineno: unterminated $thing definition"
|
|
unless $found_end;
|
|
|
|
if ($thing eq "Function") {
|
|
# Try to determine the name of the function.
|
|
foreach (@defn) {
|
|
$name = $1 if /^([\w_]+) \(/;
|
|
}
|
|
die "$progname: $input: $start_lineno: cannot find the name of this function"
|
|
unless defined $name;
|
|
}
|
|
|
|
if ($thing eq "Structure") {
|
|
push @defn, "};"
|
|
}
|
|
|
|
# Print the definition, followed by the comment.
|
|
print OUTPUT "=head4 $thing C<$input:$name>\n\n";
|
|
print OUTPUT " ", join ("\n ", @defn), "\n";
|
|
print OUTPUT "\n";
|
|
print OUTPUT join("\n", @comment), "\n";
|
|
print OUTPUT "\n";
|
|
}
|
|
}
|
|
elsif (m{^/\*\*}) {
|
|
die "$progname: $input: $lineno: special comment with incorrect format\n";
|
|
}
|
|
}
|
|
|
|
close INPUT;
|
|
}
|
|
}
|
|
|
|
close OUTPUT or die "$progname: $output: close: $!";
|
|
|
|
exit 0;
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<perlpod(1)>,
|
|
L<guestfs-hacking(1)>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Richard W.M. Jones.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2012-2016 Red Hat Inc.
|