From 01f98a250046ca40a5236ec7264aaa1ea2239adb Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Wed, 13 Apr 2016 13:47:50 +0100 Subject: [PATCH] docs: Convert more ordinary comments to internal documentation comments. --- builder/index-parser-c.c | 7 ++++--- cat/visit.c | 33 ++++++++++++++++++++++++++++++--- fish/domain.c | 10 ++++++++-- fish/edit.c | 6 ++++-- fish/help.c | 11 +++++++---- fish/keys.c | 8 +++++--- fish/lcd.c | 5 +++-- fish/man.c | 5 +++-- fish/options.c | 17 ++++++++++++++++- fish/tilde.c | 14 +++++++++----- p2v/kernel-cmdline.c | 24 ++++++++++++++---------- p2v/kernel.c | 4 +++- p2v/ssh.c | 24 +++++++++++++++--------- p2v/whole-file.c | 3 ++- python/guestfs-py-byhand.c | 5 +++-- v2v/domainxml-c.c | 3 ++- v2v/xml-c.c | 4 +++- 17 files changed, 131 insertions(+), 52 deletions(-) diff --git a/builder/index-parser-c.c b/builder/index-parser-c.c index 52c8b8632..7332f94c9 100644 --- a/builder/index-parser-c.c +++ b/builder/index-parser-c.c @@ -16,9 +16,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* This file handles the interface between the C/lex/yacc index file - * parser, and the OCaml world. See index_parser.ml for the OCaml - * type definition. +/** + * This file handles the interface between the C/lex/yacc index file + * parser, and the OCaml world. See F for + * the OCaml type definition. */ #include diff --git a/cat/visit.c b/cat/visit.c index 2e08cccf4..6a6cb1e97 100644 --- a/cat/visit.c +++ b/cat/visit.c @@ -16,9 +16,13 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* Adapted from -https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/ -*/ +/** + * This file contains a recursive function for visiting all files and + * directories in a guestfs filesystem. + * + * Adapted from + * L + */ #include @@ -36,6 +40,29 @@ https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files static int _visit (guestfs_h *g, int depth, const char *dir, visitor_function f, void *opaque); +/** + * Visit every file and directory in a guestfs filesystem, starting + * at C. + * + * C may be C<"/"> to visit the entire filesystem, or may be some + * subdirectory. Symbolic links are not followed. + * + * The visitor function C is called once for every directory and + * every file. The parameters passed to C include the current + * directory name, the current file name (or C when we're + * visiting a directory), the C (file permissions + * etc), and the list of extended attributes of the file. The visitor + * function may return C<-1> which causes the whole recursion to stop + * with an error. + * + * Also passed to this function is an C pointer which is + * passed through to the visitor function. + * + * Returns C<0> if everything went OK, or C<-1> if there was an error. + * Error handling is not particularly well defined. It will either + * set an error in the libguestfs handle or print an error on stderr, + * but there is no way for the caller to tell the difference. + */ int visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque) { diff --git a/fish/domain.c b/fish/domain.c index d3be8e774..541face3d 100644 --- a/fish/domain.c +++ b/fish/domain.c @@ -16,6 +16,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ +/** + * Implements the guestfish (and other tools) I<-d> option. + */ + #include #include @@ -26,8 +30,10 @@ #include "options.h" -/* Implements the guts of the '-d' option. - * Returns the number of drives added (> 0), or -1 for failure. +/** + * This function is called when a user invokes S>. + * + * Returns the number of drives added (S 0>>), or C<-1> for failure. */ int add_libvirt_drives (guestfs_h *g, const char *guest) diff --git a/fish/edit.c b/fish/edit.c index bf9fdb559..ead103802 100644 --- a/fish/edit.c +++ b/fish/edit.c @@ -16,6 +16,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ +/** + * guestfish edit command, suggested by Ján Ondrej. + */ + #include #include @@ -28,8 +32,6 @@ #include "fish.h" #include "file-edit.h" -/* guestfish edit command, suggested by Ján Ondrej, implemented by RWMJ */ - int run_edit (const char *cmd, size_t argc, char *argv[]) { diff --git a/fish/help.c b/fish/help.c index cf00dce02..100ae0e42 100644 --- a/fish/help.c +++ b/fish/help.c @@ -26,10 +26,13 @@ #include "fish.h" -/* The "help" command. This used to just list all commands, but - * that's not very useful. Instead display some useful - * context-sensitive help. This could be improved if we knew how many - * drives had been added already, and whether anything was mounted. +/** + * The C command. + * + * This used to just list all commands, but that's not very useful. + * Instead display some useful context-sensitive help. This could be + * improved if we knew how many drives had been added already, and + * whether anything was mounted. */ void display_help (void) diff --git a/fish/keys.c b/fish/keys.c index 4749cfc88..1c0769725 100644 --- a/fish/keys.c +++ b/fish/keys.c @@ -29,9 +29,11 @@ #include "options.h" -/* Read a passphrase ('Key') from /dev/tty with echo off. - * The caller (cmds.c) will call free on the string afterwards. - * Based on the code in cryptsetup file lib/utils.c. +/** + * Read a passphrase ('Key') from F with echo off. + * + * The caller (F) will call free on the string + * afterwards. Based on the code in cryptsetup file F. */ char * read_key (const char *param) diff --git a/fish/lcd.c b/fish/lcd.c index 8fa669c1c..d0dcdddb3 100644 --- a/fish/lcd.c +++ b/fish/lcd.c @@ -26,8 +26,9 @@ #include "fish.h" -/* guestfish lcd command (similar to the lcd command in BSD ftp) */ - +/** + * guestfish C command (similar to the C command in BSD ftp). + */ int run_lcd (const char *cmd, size_t argc, char *argv[]) { diff --git a/fish/man.c b/fish/man.c index 85b7a820c..f3e9f4e97 100644 --- a/fish/man.c +++ b/fish/man.c @@ -27,8 +27,9 @@ #include "fish.h" -/* guestfish man command */ - +/** + * guestfish C command + */ int run_man (const char *cmd, size_t argc, char *argv[]) { diff --git a/fish/options.c b/fish/options.c index ab5131b0e..679dafca5 100644 --- a/fish/options.c +++ b/fish/options.c @@ -16,6 +16,19 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ +/** + * This file contains common options parsing code used by guestfish + * and many other tools which share a common options syntax. + * + * For example, guestfish, virt-cat, virt-ls etc all support the I<-a> + * option, and that is handled in all of those tools using a macro + * C defined in C<"options.h">. + * + * There are a lot of common global variables used, C + * accumulates the list of drives, C for the I<-v> flag, and + * many more. + */ + #include #include @@ -30,7 +43,9 @@ #include "options.h" #include "uri.h" -/* Handle the '-a' option when passed on the command line. */ +/** + * Handle the guestfish I<-a> option on the command line. + */ void option_a (const char *arg, const char *format, struct drv **drvsp) { diff --git a/fish/tilde.c b/fish/tilde.c index 0d7dfa215..4e9d77f9f 100644 --- a/fish/tilde.c +++ b/fish/tilde.c @@ -34,8 +34,9 @@ static char *expand_home (char *orig, const char *append); static const char *find_home_for_username (const char *, size_t); static const char *find_home_for_current_user (void); -/* This is called from the script loop if we find a candidate for - * ~username (tilde-expansion). +/** + * This is called from the script loop if we find a candidate for + * C<~username> (tilde-expansion). */ char * try_tilde_expansion (char *str) @@ -73,7 +74,9 @@ try_tilde_expansion (char *str) return str; } -/* Return $HOME + append string. */ +/** + * Return C<$HOME> + append string. + */ static char * expand_home (char *orig, const char *append) { @@ -103,8 +106,9 @@ expand_home (char *orig, const char *append) return str; } -/* Lookup username (of length ulen), return home directory if found, - * or NULL if not found. +/** + * Lookup C (of length C), return home directory if + * found, or C if not found. */ static const char * find_home_for_username (const char *username, size_t ulen) diff --git a/p2v/kernel-cmdline.c b/p2v/kernel-cmdline.c index ee4c0e9a2..c10c04507 100644 --- a/p2v/kernel-cmdline.c +++ b/p2v/kernel-cmdline.c @@ -16,16 +16,8 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* Read /proc/cmdline. - * - * We only support double quoting, consistent with the Linux - * documentation. - * https://www.kernel.org/doc/Documentation/kernel-parameters.txt - * - * systemd supports single and double quoting and single character - * escaping, but we don't support all that. - * - * Returns a list of key, value pairs, terminated by NULL. +/** + * Mini library to read and parse C. */ #include @@ -58,6 +50,18 @@ add_string (char ***argv, size_t *lenp, const char *str, size_t len) error (EXIT_FAILURE, errno, "strndup"); } +/** + * Read and parse C. + * + * We only support double quoting, consistent with the Linux + * documentation. + * L + * + * systemd supports single and double quoting and single character + * escaping, but we don't support all that. + * + * Returns a list of key, value pairs, terminated by C. + */ char ** parse_cmdline_string (const char *cmdline) { diff --git a/p2v/kernel.c b/p2v/kernel.c index fb5278525..4e7fc9e06 100644 --- a/p2v/kernel.c +++ b/p2v/kernel.c @@ -16,7 +16,9 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* Kernel-driven configuration, non-interactive. */ +/** + * Kernel-driven, non-interactive configuration of virt-p2v. + */ #include diff --git a/p2v/ssh.c b/p2v/ssh.c index 7158e7011..765db5149 100644 --- a/p2v/ssh.c +++ b/p2v/ssh.c @@ -16,12 +16,13 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* This file handles the ssh connections to the conversion server. +/** + * This file handles the ssh connections to the conversion server. * * virt-p2v will open several connections over the lifetime of * the conversion process. * - * In 'test_connection', it will first open a connection (to check it + * In C, it will first open a connection (to check it * is possible) and query virt-v2v on the server to ensure it exists, * it is the right version, and so on. This connection is then * closed, because in the GUI case we don't want to deal with keeping @@ -30,10 +31,10 @@ * Once we start conversion, we will open a control connection to send * the libvirt configuration data and to start up virt-v2v, and we * will open up one data connection per local hard disk. The data - * connection(s) have a reverse port forward to the local qemu-nbd - * server which is serving the content of that hard disk. The remote - * port for each data connection is assigned by ssh. See - * 'open_data_connection' and 'start_remote_conversion'. + * connection(s) have a reverse port forward to the local + * L server which is serving the content of that hard + * disk. The remote port for each data connection is assigned by ssh. + * See C and C. */ #include @@ -164,7 +165,9 @@ free_regexps (void) pcre_free (portfwd_re); } -/* Download URL to local file using the external 'curl' command. */ +/** + * Download URL to local file using the external 'curl' command. + */ static int curl_download (const char *url, const char *local_file) { @@ -223,7 +226,9 @@ curl_download (const char *url, const char *local_file) return 0; } -/* Re-cache the identity_url if needed. */ +/** + * Re-cache the Cidentity_url> if needed. + */ static int cache_ssh_identity (struct config *config) { @@ -255,7 +260,8 @@ cache_ssh_identity (struct config *config) return 0; } -/* Start ssh subprocess with the standard arguments and possibly some +/** + * Start ssh subprocess with the standard arguments and possibly some * optional arguments. Also handles authentication. */ static mexp_h * diff --git a/p2v/whole-file.c b/p2v/whole-file.c index 90df71676..c5e6a25b3 100644 --- a/p2v/whole-file.c +++ b/p2v/whole-file.c @@ -27,7 +27,8 @@ #include "p2v.h" -/* Read the whole file into a memory buffer and return it. The file +/** + * Read the whole file into a memory buffer and return it. The file * should be a regular, local, trusted file. */ int diff --git a/python/guestfs-py-byhand.c b/python/guestfs-py-byhand.c index b200dc638..cf8576fa3 100644 --- a/python/guestfs-py-byhand.c +++ b/python/guestfs-py-byhand.c @@ -16,9 +16,10 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ -/* This file contains a small number of functions that are written by +/** + * This file contains a small number of functions that are written by * hand. The majority of the bindings are generated (see - * guestfs-py.c). + * F). */ /* This has to be included first, else definitions conflict with diff --git a/v2v/domainxml-c.c b/v2v/domainxml-c.c index 4876f949e..06a93eb42 100644 --- a/v2v/domainxml-c.c +++ b/v2v/domainxml-c.c @@ -16,7 +16,8 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* This module implements various [virsh]-like commands, but with +/** + * This module implements various C-like commands, but with * non-broken authentication handling. */ diff --git a/v2v/xml-c.c b/v2v/xml-c.c index ecaaedf19..1abfe6479 100644 --- a/v2v/xml-c.c +++ b/v2v/xml-c.c @@ -16,7 +16,9 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/* Mini interface to libxml2. */ +/** + * Mini interface to libxml2. + */ #include