diff --git a/examples/debug-logging.c b/examples/debug-logging.c
index 4b2451bb8..0836fef5c 100644
--- a/examples/debug-logging.c
+++ b/examples/debug-logging.c
@@ -41,23 +41,33 @@ main (int argc, char *argv[])
                                   event_bitmask, 0, NULL) == -1)
     exit (EXIT_FAILURE);
 
-  /* This is how debugging is enabled: Setting the 'trace' flag in the
-   * handle means that each libguestfs call is logged.  Setting the
-   * 'verbose' flag enables a great deal of extra debugging throughout
-   * the system.  Note that you should set the flags early on after
-   * creating the handle.
+  /* This is how debugging is enabled:
+   *
+   * Setting the 'trace' flag in the handle means that each libguestfs
+   * call is logged (name, parameters, return).  This flag is useful
+   * to see how libguestfs is being used by a program.
+   *
+   * Setting the 'verbose' flag enables a great deal of extra
+   * debugging throughout the system.  This is useful if there is a
+   * libguestfs error which you don't understand.
+   *
+   * Note that you should set the flags early on after creating the
+   * handle.  In particular if you set the verbose flag after launch
+   * then you won't see all messages.
    *
    * For more information see:
    * http://libguestfs.org/guestfs-faq.1.html#debugging-libguestfs
    *
-   * Note that error messages raised by APIs are *not* debugging or
-   * trace information, and they are not affected by any of this.  You
-   * may have to log them separately.
+   * Error messages raised by APIs are *not* debugging information,
+   * and they are not affected by any of this.  You may have to log
+   * them separately.
    */
   guestfs_set_trace (g, 1);
   guestfs_set_verbose (g, 1);
 
-  /* Add a dummy disk image. */
+  /* Do some operations which will generate plenty of trace and debug
+   * messages.
+   */
   if (guestfs_add_drive (g, "/dev/null") == -1)
     exit (EXIT_FAILURE);
 
@@ -65,11 +75,9 @@ main (int argc, char *argv[])
           "Take a look in your system log file,\n"
           "eg. /var/log/messages.\n");
 
-  /* Run the libguestfs back-end. */
   if (guestfs_launch (g) == -1)
     exit (EXIT_FAILURE);
 
-  /* ... and close. */
   guestfs_close (g);
 
   exit (EXIT_SUCCESS);