mirrors/libguestfs
1
0
Fork 0
mirror of https://github.com/libguestfs/libguestfs.git synced 2026-03-22 07:03:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: internal: Allow headers and structs to be documented.

Browse Source 
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.
This commit is contained in:
Richard W.M. Jones
2016-10-25 12:49:15 +01:00
parent 8823247bd5
commit 4d535c7038
11 changed files with 207 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile.am
View File

@@ -307,7 +307,7 @@ ChangeLog: configure.ac
# to DIST_SUBDIRS.
docs/C_SOURCE_FILES: configure.ac
rm -f $@ $@-t
find $(DIST_SUBDIRS) -name '*.c' | \
find $(DIST_SUBDIRS) -name '*.[ch]' | \
grep -v -E '^(builder/index-parse.c|builder/index-scan.c|examples/|gnulib/|gobject/|perl/|tests/|test-data/)' | \
grep -v -E '/((guestfs|rc)_protocol\.c)$$' | \
grep -v -E '.*/errnostring\.c$$' | \

49
docs/C_SOURCE_FILES
View File

@@ -1,6 +1,8 @@
align/scan.c
builder/index-parse.h
builder/index-parser-c.c
builder/index-struct.c
builder/index-struct.h
builder/index-validate.c
builder/pxzcat-c.c
builder/setlocale-c.c
@@ -11,11 +13,13 @@ cat/log.c
cat/ls.c
cat/tail.c
cat/visit.c
cat/visit.h
customize/crypt-c.c
customize/dummy.c
customize/perl_edit-c.c
daemon/9p.c
daemon/acl.c
daemon/actions.h
daemon/augeas.c
daemon/available.c
daemon/base64.c
@@ -26,12 +30,15 @@ daemon/btrfs.c
daemon/cap.c
daemon/checksum.c
daemon/cleanups.c
daemon/cleanups.h
daemon/cmp.c
daemon/command.c
daemon/command.h
daemon/compress.c
daemon/copy.c
daemon/cpio.c
daemon/cpmv.c
daemon/daemon.h
daemon/dd.c
daemon/debug-bmap.c
daemon/debug.c
@@ -43,6 +50,7 @@ daemon/dmesg.c
daemon/dropcaches.c
daemon/du.c
daemon/echo-daemon.c
daemon/errnostring.h
daemon/ext2.c
daemon/fallocate.c
daemon/file.c
@@ -56,6 +64,7 @@ daemon/fstrim.c
daemon/glob.c
daemon/grep.c
daemon/grub.c
daemon/guestfs_protocol.h
daemon/guestfsd.c
daemon/headtail.c
daemon/hexdump.c
@@ -87,6 +96,7 @@ daemon/names.c
daemon/ntfs.c
daemon/ntfsclone.c
daemon/optgroups.c
daemon/optgroups.h
daemon/parted.c
daemon/pingdaemon.c
daemon/proto.c
@@ -111,6 +121,7 @@ daemon/stubs-3.c
daemon/stubs-4.c
daemon/stubs-5.c
daemon/stubs-6.c
daemon/stubs.h
daemon/swap.c
daemon/sync.c
daemon/syslinux.c
@@ -129,10 +140,14 @@ daemon/zero.c
daemon/zerofree.c
df/df.c
df/domains.c
df/domains.h
df/estimate-max-threads.c
df/estimate-max-threads.h
df/main.c
df/output.c
df/parallel.c
df/parallel.h
df/virt-df.h
dib/dummy.c
diff/diff.c
edit/edit.c
@@ -143,10 +158,12 @@ erlang/actions-3.c
erlang/actions-4.c
erlang/actions-5.c
erlang/actions-6.c
erlang/actions.h
erlang/dispatch.c
erlang/main.c
erlang/structs.c
fish/alloc.c
fish/cmds-gperf.h
fish/cmds.c
fish/completion.c
fish/config.c
@@ -154,6 +171,7 @@ fish/copy.c
fish/decrypt.c
fish/destpaths.c
fish/display-options.c
fish/display-options.h
fish/display.c
fish/domain.c
fish/echo.c
@@ -168,7 +186,10 @@ fish/entries-6.c
fish/event-names.c
fish/events.c
fish/file-edit.c
fish/file-edit.h
fish/fish-cmds.h
fish/fish.c
fish/fish.h
fish/glob.c
fish/help.c
fish/hexedit.c
@@ -178,6 +199,7 @@ fish/lcd.c
fish/man.c
fish/more.c
fish/options.c
fish/options.h
fish/prep-boot.c
fish/prep-disk.c
fish/prep-fs.c
@@ -185,8 +207,11 @@ fish/prep-lv.c
fish/prep-part.c
fish/prep.c
fish/prepopts.c
fish/prepopts.h
fish/progress.c
fish/progress.h
fish/rc.c
fish/rc_protocol.h
fish/reopen.c
fish/run-0.c
fish/run-1.c
@@ -195,12 +220,15 @@ fish/run-3.c
fish/run-4.c
fish/run-5.c
fish/run-6.c
fish/run.h
fish/setenv.c
fish/supported.c
fish/tilde.c
fish/time.c
fish/uri.c
fish/uri.h
fish/windows.c
fish/windows.h
format/format.c
fuse/guestmount.c
fuse/guestunmount.c
@@ -216,6 +244,7 @@ java/actions-3.c
java/actions-4.c
java/actions-5.c
java/actions-6.c
java/com_redhat_et_libguestfs_GuestFS.h
java/handle.c
lua/lua-guestfs.c
make-fs/make-fs.c
@@ -232,19 +261,25 @@ mllib/uri-c.c
ocaml/guestfs-c-actions.c
ocaml/guestfs-c-errnos.c
ocaml/guestfs-c.c
ocaml/guestfs-c.h
p2v/about-authors.c
p2v/about-license.c
p2v/config.c
p2v/conversion.c
p2v/gui.c
p2v/inhibit.c
p2v/kernel-cmdline.c
p2v/kernel.c
p2v/main.c
p2v/miniexpect.c
p2v/miniexpect.h
p2v/p2v.h
p2v/ssh.c
p2v/utils.c
p2v/whole-file.c
php/extension/config.h
php/extension/guestfs_php.c
php/extension/php_guestfs_php.h
python/actions-0.c
python/actions-1.c
python/actions-2.c
@@ -252,6 +287,7 @@ python/actions-3.c
python/actions-4.c
python/actions-5.c
python/actions-6.c
python/actions.h
python/handle.c
python/module.c
python/structs.c
@@ -264,6 +300,8 @@ ruby/ext/guestfs/actions-3.c
ruby/ext/guestfs/actions-4.c
ruby/ext/guestfs/actions-5.c
ruby/ext/guestfs/actions-6.c
ruby/ext/guestfs/actions.h
ruby/ext/guestfs/extconf.h
ruby/ext/guestfs/handle.c
ruby/ext/guestfs/module.c
sparsify/dummy.c
@@ -288,12 +326,20 @@ src/copy-in-out.c
src/create.c
src/dbdump.c
src/drives.c
src/errnostring.h
src/errors.c
src/event-string.c
src/events.c
src/file.c
src/filearch.c
src/fuse.c
src/guestfs-internal-actions.h
src/guestfs-internal-all.h
src/guestfs-internal-frontend-cleanups.h
src/guestfs-internal-frontend.h
src/guestfs-internal.h
src/guestfs.h
src/guestfs_protocol.h
src/guid.c
src/handle.c
src/info.c
@@ -327,6 +373,7 @@ src/structs-compare.c
src/structs-copy.c
src/structs-free.c
src/structs-print.c
src/structs-print.h
src/tmpdirs.c
src/tsk.c
src/uefi.c
@@ -340,7 +387,9 @@ sysprep/dummy.c
test-tool/test-tool.c
utils/boot-analysis/boot-analysis-timeline.c
utils/boot-analysis/boot-analysis-utils.c
utils/boot-analysis/boot-analysis-utils.h
utils/boot-analysis/boot-analysis.c
utils/boot-analysis/boot-analysis.h
utils/boot-benchmark/boot-benchmark.c
utils/qemu-boot/qemu-boot.c
utils/qemu-speed-test/qemu-speed-test.c

80
docs/make-internal-documentation.pl
View File

@@ -38,21 +38,32 @@ 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 look like this:
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 function being documented should appear immediately after the
special comment, and is also copied into the documentation.
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.
@@ -118,7 +129,7 @@ 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 files
# - are C source or header files
# - exist
# - contain /** comments.
@@ -126,7 +137,7 @@ my @inputs = ();
my $input;
my $path;
foreach $input (@ARGV) {
if ($input =~ /\.c$/) {
if ($input =~ /\.[ch]$/) {
$path = "$srcdir/$input";
if (-r $path) {
my @cmd = ("grep", "-q", "^/\\*\\*", $path);
@@ -212,39 +223,62 @@ foreach $dir (@dirs) {
print OUTPUT "\n";
}
else {
# Otherwise it's a function description, so now we
# need to read in the function definition.
my @function = ();
# 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 (m/^{/) {
$found_end = 1;
last;
if (defined $end) {
if ($_ eq $end) {
$found_end = 1;
last;
}
else {
push @defn, $_;
}
}
else {
push @function, $_;
# 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 function definition"
die "$progname: $input: $start_lineno: unterminated $thing definition"
unless $found_end;
# Try to determine the name of the function.
my $function;
foreach (@function) {
$function = $1 if /^([\w_]+) \(/;
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;
}
die "$progname: $input: $start_lineno: cannot find the name of this function"
unless defined $function;
# Print the function definition, followed by the
# comment.
print OUTPUT "=head4 Function C<$input:$function>\n\n";
print OUTPUT " ", join ("\n ", @function), "\n";
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";

22
fish/file-edit.c
View File

@@ -52,6 +52,20 @@ static char *generate_random_name (const char *filename);
static char *generate_backup_name (const char *filename,
const char *backup_extension);
/**
* Edit C<filename> using the specified C<editor> application.
*
* If C<backup_extension> is not null, then a copy of C<filename> is
* saved with C<backup_extension> appended to its file name.
*
* If C<editor> is null, then the C<$EDITOR> environment variable will
* be queried for the editor application, leaving C<vi> as fallback if
* not set.
*
* Returns C<-1> for failure, C<0> on success, C<1> if the editor did
* not change the file (e.g. the user closed the editor without
* saving).
*/
int
edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
const char *backup_extension, int verbose)
@@ -127,6 +141,14 @@ edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
return 0;
}
/**
* Edit C<filename> running the specified C<perl_expr> using Perl.
*
* If C<backup_extension> is not null, then a copy of C<filename> is
* saved with C<backup_extension> appended to its file name.
*
* Returns C<-1> for failure, C<0> on success.
*/
int
edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
const char *backup_extension, int verbose)

18
fish/file-edit.h
View File

@@ -21,28 +21,10 @@
#include <guestfs.h>
/**
* Edit 'filename' using the specified 'editor' application.
* If 'backup_extension' is not null, then a copy of 'filename' is saved
* with 'backup_extension' appended to its file name.
* If 'editor' is null, then the EDITOR environment variable
* will be queried for the editor application, leaving "vi" as fallback
* if not set.
*
* Returns -1 for failure, 0 on success, 1 if the editor did not change
* the file (e.g. the user closed the editor without saving).
*/
extern int edit_file_editor (guestfs_h *g, const char *filename,
const char *editor, const char *backup_extension,
int verbose);
/**
* Edit 'filename' running the specified 'perl_expr' using Perl.
* If 'backup_extension' is not null, then a copy of 'filename' is saved
* with 'backup_extension' appended to its file name.
*
* Returns -1 for failure, 0 otherwise (on success).
*/
extern int edit_file_perl (guestfs_h *g, const char *filename,
const char *perl_expr,
const char *backup_extension, int verbose);

32
fish/windows.c
View File

@@ -41,6 +41,11 @@
static void mount_drive_letter (guestfs_h *g, char drive_letter,
const char *root, int readonly);
/**
* Checks whether C<root> is a Windows installation.
*
* This relies on an already being done introspection.
*/
int
is_windows (guestfs_h *g, const char *root)
{
@@ -53,6 +58,33 @@ is_windows (guestfs_h *g, const char *root)
return w;
}
/**
* Resolves C<path> as possible Windows path according to C<root>,
* giving a new path that can be used in libguestfs API calls.
*
* Notes:
*
* =over 4
*
* =item *
*
* C<root> must be a Windows installation
*
* =item *
*
* relies on an already being done introspection
*
* =item *
*
* will unmount all the existing mount points and mount the Windows root
* (according to C<readonly>)
*
* =item *
*
* calls L<exit(3)> on memory allocation failures
*
* =back
*/
char *
windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
{

16
fish/windows.h
View File

@@ -21,24 +21,8 @@
#include <guestfs.h>
/**
* Checks whether 'root' is a Windows installation.
*
* This relies on an already being done introspection.
*/
extern int is_windows (guestfs_h *g, const char *root);
/**
* Resolves 'path' as possible Windows path according to 'root',
* giving a new path that can be used in libguestfs API calls.
*
* Notes:
* - 'root' must be a Windows installation
* - relies on an already being done introspection
* - will unmount all the existing mount points and mount the Windows root
* (according to 'readonly')
* - will exit() on memory allocation failures
*/
extern char *windows_path (guestfs_h *g, const char *root, const char *path,
int readonly);

13
src/guestfs-internal-all.h
View File

@@ -16,8 +16,17 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/* NB: This contains ONLY definitions which are shared by libguestfs
* daemon, library, bindings and tools (ie. ALL C code).
/**
* This header contains definitions which are shared by all parts of
* libguestfs, ie. the daemon, the library, language bindings and virt
* tools (ie. I<all> C code).
*
* If you need a definition used by only the library, put it in
* F<src/guestfs-internal.h> instead. If you need a definition used
* by only the frontend (non-daemon) parts of libguestfs, try
* F<src/guestfs-internal-frontend.h>. If a definition is used by
* only a single tool, it should not be in any shared header file at
* all.
*/
#ifndef GUESTFS_INTERNAL_ALL_H_

16
src/guestfs-internal-frontend.h
View File

@@ -16,15 +16,17 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/* NB: This contains ONLY definitions which are shared by libguestfs
* library, bindings, tools and tests (NOT the daemon).
/**
* This header file is included in all "frontend" parts of libguestfs,
* namely the library, non-C language bindings, virt tools and tests.
*
* If a definition is only needed by a single component of libguestfs,
* then it should NOT be here!
*
* The daemon does NOT use this header. If you need a place to put
* The daemon does B<not> use this header. If you need a place to put
* something shared with absolutely everything including the daemon,
* put it in 'src/guestfs-internal-all.h'.
* put it in F<src/guestfs-internal-all.h>
*
* If a definition is only needed by a single component of libguestfs
* (eg. just the library, or just a single virt tool) then it should
* B<not> be here!
*/
#ifndef GUESTFS_INTERNAL_FRONTEND_H_

8
src/guestfs-internal.h
View File

@@ -16,6 +16,14 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* This header file is included in the libguestfs library (F<src/>)
* only.
*
* See also F<src/guestfs-internal-frontend.h> and
* F<src/guestfs-internal-all.h>
*/
#ifndef GUESTFS_INTERNAL_H_
#define GUESTFS_INTERNAL_H_

21
src/private-data.c
View File

@@ -16,6 +16,17 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* Implement a private data area where libguestfs C API users can
* attach arbitrary pieces of data to a C<guestfs_h> handle.
*
* For more information see L<guestfs(3)/PRIVATE DATA AREA>.
*
* Language bindings do not generally expose this, largely because in
* non-C languages it is easy to associate data with handles in other
* ways (using hash tables or maps).
*/
#include <config.h>
#include <stdio.h>
@@ -29,9 +40,13 @@
#include "guestfs.h"
#include "guestfs-internal.h"
/* Note the private data area is allocated lazily, since the vast
* majority of callers will never use it. This means g->pda is
* likely to be NULL.
/**
* The private data area is internally stored as a gnulib hash
* table containing C<pda_entry> structures.
*
* Note the private data area is allocated lazily, since the vast
* majority of callers will never use it. This means C<g-E<gt>pda> is
* likely to be C<NULL>.
*/
struct pda_entry {
char *key; /* key */