diff --git a/df/domains.c b/df/domains.c
index c65164584..d5d3ae9a1 100644
--- a/df/domains.c
+++ b/df/domains.c
@@ -16,6 +16,16 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+/**
+ * This file is used by C<virt-df> and some of the other tools
+ * when they are implicitly asked to operate over all libvirt
+ * domains (VMs), for example when C<virt-df> is called without
+ * specifying any particular disk image.
+ *
+ * It hides the complexity of querying the list of domains from
+ * libvirt.
+ */
+
 #include <config.h>
 
 #include <stdio.h>
@@ -49,6 +59,9 @@ compare_domain_names (const void *p1, const void *p2)
   return strcmp (d1->name, d2->name);
 }
 
+/**
+ * Frees up everything allocated by C<get_all_libvirt_domains>.
+ */
 void
 free_domains (void)
 {
@@ -70,6 +83,11 @@ static void add_domains_by_id (virConnectPtr conn, int *ids, size_t n);
 static void add_domains_by_name (virConnectPtr conn, char **names, size_t n);
 static void add_domain (virDomainPtr dom);
 
+/**
+ * Read all libguest guests into the global variables C<domains> and
+ * C<nr_domains>.  The guests are ordered by name.  This exits on any
+ * error.
+ */
 void
 get_all_libvirt_domains (const char *libvirt_uri)
 {
diff --git a/df/domains.h b/df/domains.h
index fd0f9a061..abbbf0794 100644
--- a/df/domains.h
+++ b/df/domains.h
@@ -33,13 +33,8 @@ struct domain {
 extern struct domain *domains;
 extern size_t nr_domains;
 
-/* Frees up everything used by 'domains.c'. */
 extern void free_domains (void);
 
-/* Read all libguest guests into the global variables 'domains' and
- * 'nr_domains'.  The guests are ordered by name.  This exits on any
- * error.
- */
 extern void get_all_libvirt_domains (const char *libvirt_uri);
 
 #endif /* HAVE_LIBVIRT */
diff --git a/df/estimate-max-threads.c b/df/estimate-max-threads.c
index ca1fd4264..27ed80db9 100644
--- a/df/estimate-max-threads.c
+++ b/df/estimate-max-threads.c
@@ -36,6 +36,11 @@ static char *read_line_from (const char *cmd);
  */
 #define MBYTES_PER_THREAD 650
 
+/**
+ * This function uses the output of C<free -m> to estimate how many
+ * libguestfs appliances could be safely started in parallel.  Note
+ * that it always returns E<ge> 1.
+ */
 size_t
 estimate_max_threads (void)
 {
@@ -54,7 +59,9 @@ estimate_max_threads (void)
   return MAX (1, mbytes / MBYTES_PER_THREAD);
 }
 
-/* Run external command and read the first line of output. */
+/**
+ * Run external command and read the first line of output.
+ */
 static char *
 read_line_from (const char *cmd)
 {
diff --git a/df/estimate-max-threads.h b/df/estimate-max-threads.h
index 11d458c08..0114cdc93 100644
--- a/df/estimate-max-threads.h
+++ b/df/estimate-max-threads.h
@@ -19,10 +19,6 @@
 #ifndef GUESTFS_ESTIMATE_MAX_THREADS_H_
 #define GUESTFS_ESTIMATE_MAX_THREADS_H_
 
-/* This function uses the output of 'free -m' to estimate how many
- * libguestfs appliances could be safely started in parallel.  Note
- * that it always returns >= 1.
- */
 extern size_t estimate_max_threads (void);
 
 #endif /* GUESTFS_ESTIMATE_MAX_THREADS_H_ */
diff --git a/df/parallel.c b/df/parallel.c
index aa37bc334..d8aa37516 100644
--- a/df/parallel.c
+++ b/df/parallel.c
@@ -16,6 +16,16 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+/**
+ * This file is used by C<virt-df> and some of the other tools when
+ * they need to run multiple parallel libguestfs instances to operate
+ * on a large number of libvirt domains efficiently.
+ *
+ * It implements a multithreaded work queue.  In addition it reorders
+ * the output so the output still appears in the same order as the
+ * input (ie. still ordered alphabetically).
+ */
+
 #include <config.h>
 
 #include <stdio.h>
@@ -76,7 +86,26 @@ struct thread_data {
   int r;                        /* Used to store the error status. */
 };
 
-/* Start threads. */
+/**
+ * Run the threads and work through the global list of libvirt
+ * domains.
+ *
+ * C<option_P> is whatever the user passed in the I<-P> option, or
+ * C<0> if the user didn't use the I<-P> option (in which case the
+ * number of threads is chosen heuristically).
+ *
+ * C<options_handle> (which may be C<NULL>) is the global guestfs
+ * handle created by the options mini-library.
+ *
+ * The work function (C<work>) should do the work (inspecting the
+ * domain, etc.)  on domain index C<i>.  However it I<must not> print
+ * out any result directly.  Instead it prints anything it needs to
+ * the supplied C<FILE *>.  The work function should return C<0> on
+ * success or C<-1> on error.
+ *
+ * The C<start_threads> function returns C<0> if all work items
+ * completed successfully, or C<-1> if there was an error.
+ */
 int
 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
 {
@@ -134,7 +163,6 @@ start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
   return errors == 0 ? 0 : -1;
 }
 
-/* Worker thread. */
 static void *
 worker_thread (void *thread_data_vp)
 {
diff --git a/df/parallel.h b/df/parallel.h
index 44f03bca8..1b88f1c90 100644
--- a/df/parallel.h
+++ b/df/parallel.h
@@ -23,24 +23,8 @@
 
 #include "domains.h"
 
-/* The work function should do the work (inspecting the domain, etc.)
- * on domain index 'i'.  However it MUST NOT print out any result
- * directly.  Instead it prints anything it needs to the supplied
- * 'FILE *'.
- * Returns 0 on success or -1 on error.
- */
 typedef int (*work_fn) (guestfs_h *g, size_t i, FILE *fp);
 
-/* Run the threads and work through the global list of libvirt
- * domains.  'option_P' is whatever the user passed in the '-P'
- * option, or 0 if the user didn't use the '-P' option (in which case
- * the number of threads is chosen heuristically).  'options_handle'
- * (which may be NULL) is the global guestfs handle created by the
- * options mini-library.
- *
- * Returns 0 if all work items completed successfully, or -1 if there
- * was an error.
- */
 extern int start_threads (size_t option_P, guestfs_h *options_handle, work_fn work);
 
 #endif /* HAVE_LIBVIRT */