docs: Convert more ordinary comments to internal documentation comments.

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<builder/index_parser.ml> for
+ * the OCaml type definition.
  */
 
 #include <config.h>

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<https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/>
+ */
 
 #include <config.h>
 
@@ -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<dir>.
+ *
+ * C<dir> may be C<"/"> to visit the entire filesystem, or may be some
+ * subdirectory.  Symbolic links are not followed.
+ *
+ * The visitor function C<f> is called once for every directory and
+ * every file.  The parameters passed to C<f> include the current
+ * directory name, the current file name (or C<NULL> when we're
+ * visiting a directory), the C<guestfs_statns> (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<opaque> 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)
 {

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 <config.h>
 
 #include <stdio.h>
@@ -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<C<guestfish -d guest>>.
+ *
+ * Returns the number of drives added (S<C<E<gt> 0>>), or C<-1> for failure.
  */
 int
 add_libvirt_drives (guestfs_h *g, const char *guest)

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 <config.h>
 
 #include <stdio.h>
@@ -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[])
 {

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<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.
  */
 void
 display_help (void)

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</dev/tty> with echo off.
+ *
+ * The caller (F<fish/cmds.c>) will call free on the string
+ * afterwards.  Based on the code in cryptsetup file F<lib/utils.c>.
  */
 char *
 read_key (const char *param)

fish/lcd.c

@@ -26,8 +26,9 @@
 
 #include "fish.h"
 
-/* guestfish lcd command (similar to the lcd command in BSD ftp) */
-
+/**
+ * guestfish C<lcd> command (similar to the C<lcd> command in BSD ftp).
+ */
 int
 run_lcd (const char *cmd, size_t argc, char *argv[])
 {

fish/man.c

@@ -27,8 +27,9 @@
 
 #include "fish.h"
 
-/* guestfish man command */
-
+/**
+ * guestfish C<man> command
+ */
 int
 run_man (const char *cmd, size_t argc, char *argv[])
 {

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<OPTION_a> defined in C<"options.h">.
+ *
+ * There are a lot of common global variables used, C<drvs>
+ * accumulates the list of drives, C<verbose> for the I<-v> flag, and
+ * many more.
+ */
+
 #include <config.h>
 
 #include <stdio.h>
@@ -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)
 {

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<username> (of length C<ulen>), return home directory if
+ * found, or C<NULL> if not found.
  */
 static const char *
 find_home_for_username (const char *username, size_t ulen)

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</proc/cmdline>.
  */
 
 #include <config.h>
@@ -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</proc/cmdline>.
+ *
+ * We only support double quoting, consistent with the Linux
+ * documentation.
+ * L<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 C<NULL>.
+ */
 char **
 parse_cmdline_string (const char *cmdline)
 {

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 <config.h>
 

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<test_connection>, 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<qemu-nbd(8)> server which is serving the content of that hard
+ * disk.  The remote port for each data connection is assigned by ssh.
+ * See C<open_data_connection> and C<start_remote_conversion>.
  */
 
 #include <config.h>
@@ -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 C<config-E<gt>identity_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 *

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

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<python/guestfs-py.c>).
  */
 
 /* This has to be included first, else definitions conflict with

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<virsh>-like commands, but with
  * non-broken authentication handling.
  */
 

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 <config.h>