From 4d535c7038ee71436f74ae30b397ddfb866d54f1 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 25 Oct 2016 12:49:15 +0100 Subject: [PATCH] docs: internal: Allow headers and structs to be documented. 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. --- Makefile.am | 2 +- docs/C_SOURCE_FILES | 49 ++++++++++++++++++ docs/make-internal-documentation.pl | 80 ++++++++++++++++++++--------- fish/file-edit.c | 22 ++++++++ fish/file-edit.h | 18 ------- fish/windows.c | 32 ++++++++++++ fish/windows.h | 16 ------ src/guestfs-internal-all.h | 13 ++++- src/guestfs-internal-frontend.h | 16 +++--- src/guestfs-internal.h | 8 +++ src/private-data.c | 21 ++++++-- 11 files changed, 207 insertions(+), 70 deletions(-) diff --git a/Makefile.am b/Makefile.am index 663958d7b..d37016cf4 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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$$' | \ diff --git a/docs/C_SOURCE_FILES b/docs/C_SOURCE_FILES index 028a64bf1..5b8350e8d 100644 --- a/docs/C_SOURCE_FILES +++ b/docs/C_SOURCE_FILES @@ -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 diff --git a/docs/make-internal-documentation.pl b/docs/make-internal-documentation.pl index 5656b6bb9..b5e5a2c23 100755 --- a/docs/make-internal-documentation.pl +++ b/docs/make-internal-documentation.pl @@ -38,21 +38,32 @@ L. 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 equals C. */ bool is_equal (const char *foo, const char *bar) + { + ... + + /** + * Struct used to store Cs. + */ + struct foo_bar { ... The comment is written in POD format (see L). 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 () { 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"; diff --git a/fish/file-edit.c b/fish/file-edit.c index d8b7e2a50..e875b5bd2 100644 --- a/fish/file-edit.c +++ b/fish/file-edit.c @@ -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 using the specified C application. + * + * If C is not null, then a copy of C is + * saved with C appended to its file name. + * + * If C is null, then the C<$EDITOR> environment variable will + * be queried for the editor application, leaving C 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 running the specified C using Perl. + * + * If C is not null, then a copy of C is + * saved with C 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) diff --git a/fish/file-edit.h b/fish/file-edit.h index cd92e5aa8..a99229b6a 100644 --- a/fish/file-edit.h +++ b/fish/file-edit.h @@ -21,28 +21,10 @@ #include -/** - * 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); diff --git a/fish/windows.c b/fish/windows.c index 91eafad8c..3a37be93f 100644 --- a/fish/windows.c +++ b/fish/windows.c @@ -41,6 +41,11 @@ static void mount_drive_letter (guestfs_h *g, char drive_letter, const char *root, int readonly); +/** + * Checks whether C 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 as possible Windows path according to C, + * giving a new path that can be used in libguestfs API calls. + * + * Notes: + * + * =over 4 + * + * =item * + * + * C 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) + * + * =item * + * + * calls L on memory allocation failures + * + * =back + */ char * windows_path (guestfs_h *g, const char *root, const char *path, int readonly) { diff --git a/fish/windows.h b/fish/windows.h index f684784f1..9ffa80264 100644 --- a/fish/windows.h +++ b/fish/windows.h @@ -21,24 +21,8 @@ #include -/** - * 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); diff --git a/src/guestfs-internal-all.h b/src/guestfs-internal-all.h index af30e58eb..bae42c221 100644 --- a/src/guestfs-internal-all.h +++ b/src/guestfs-internal-all.h @@ -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 C code). + * + * If you need a definition used by only the library, put it in + * F instead. If you need a definition used + * by only the frontend (non-daemon) parts of libguestfs, try + * F. 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_ diff --git a/src/guestfs-internal-frontend.h b/src/guestfs-internal-frontend.h index da7709a7c..bc5750602 100644 --- a/src/guestfs-internal-frontend.h +++ b/src/guestfs-internal-frontend.h @@ -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 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 + * + * 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 be here! */ #ifndef GUESTFS_INTERNAL_FRONTEND_H_ diff --git a/src/guestfs-internal.h b/src/guestfs-internal.h index d437b9a18..092c6d579 100644 --- a/src/guestfs-internal.h +++ b/src/guestfs-internal.h @@ -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) + * only. + * + * See also F and + * F + */ + #ifndef GUESTFS_INTERNAL_H_ #define GUESTFS_INTERNAL_H_ diff --git a/src/private-data.c b/src/private-data.c index 3f6e6f11f..64fe9ef87 100644 --- a/src/private-data.c +++ b/src/private-data.c @@ -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 handle. + * + * For more information see L. + * + * 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 #include @@ -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 structures. + * + * Note the private data area is allocated lazily, since the vast + * majority of callers will never use it. This means Cpda> is + * likely to be C. */ struct pda_entry { char *key; /* key */