o Let the comment wars begin.

lib/format_text/backup.c

@@ -22,14 +22,13 @@
 
 
 /*
- * The format instance is given a directory path
+ * The format instance is given a directory path upon creation.
- * upon creation.  Each file in this directory
+ * Each file in this directory whose name is of the form
- * whose name is of the form '(.*)_[0-9]*.vg' is a config
+ * '(.*)_[0-9]*.vg' is a config file (see lib/config.[hc]), which
- * file (see lib/config.[hc]), which contains a
+ * contains a description of a single volume group.
- * description of a single volume group.
  *
- * The prefix ($1 from the above regex) of the
+ * The prefix ($1 from the above regex) of the config file gives
- * config file gives the volume group name.
+ * the volume group name.
  *
  * Backup files that have expired will be removed.
  */
@@ -41,23 +40,20 @@ struct backup_c {
 	char *dir;
 
 	/*
-	 * An ordered list of previous backups.
+	 * An ordered list of previous backups.  Each list
-	 * Each list entered against the vg name.
+	 * entered against the vg name.  Most recent first.
-	 * Most recent first.
 	 */
 	struct hash_table *vg_backups;
 
 	/*
-	 * Scratch pool.  Contents of vg_backups
+	 * Scratch pool.  Contents of vg_backups come from here.
-	 * come from here.
 	 */
 	struct pool *mem;
 };
 
 /*
- * A list of these is built up for each volume
+ * A list of these is built up for each volume group.  Ordered
- * group.  Ordered with the least recent at the
+ * with the least recent at the head.
- * head.
  */
 struct backup_file {
 	struct list list;
@@ -130,8 +126,7 @@ static void _destroy(struct format_instance *fi)
 
 
 /*
- * Extract vg name and version number from a
+ * Extract vg name and version number from a filename.
- * filename
  */
 static int _split_vg(const char *filename, char *vg, size_t vg_size,
 		     uint32_t *index)
@@ -193,8 +188,8 @@ static int _scan_vg(struct backup_c *bc, const char *file,
 	struct list *files;
 
 	/*
-	 * Do we need to create a new list of
+	 * Do we need to create a new list of backup files for
-	 * backup files for this vg ?
+	 * this vg ?
 	 */
 	if (!(files = hash_lookup(bc->vg_backups, vg_name))) {
 		if (!(files = pool_alloc(bc->mem, sizeof(*files)))) {
@@ -223,8 +218,7 @@ static int _scan_vg(struct backup_c *bc, const char *file,
 	b->vg = (char *)vg_name;
 
 	/*
-	 * Insert it to the correct part of the
+	 * Insert it to the correct part of the list.
-	 * list.
 	 */
 	_insert_file(files, b);
 
@@ -300,12 +294,10 @@ static int _scan_backups(struct backup_c *bc)
 }
 
 /*
- * Creates a temporary filename, and opens a
+ * Creates a temporary filename, and opens a descriptor to the
- * descriptor to the file.  Both the filename and
+ * file.  Both the filename and descriptor are needed so we can
- * descriptor are needed so we can rename the file
+ * rename the file after successfully writing it.  Grab
- * after successfully writing it.  Grab
+ * NFS-supported exclusive fcntl discretionary lock.
- * NFS-supported exclusive fcntl discretionary
- * lock.
  */
 static int _create_temp_name(const char *dir, char *buffer, size_t len,
 			     int *fd)
@@ -351,15 +343,14 @@ static int _create_temp_name(const char *dir, char *buffer, size_t len,
 }
 
 /*
- * NFS-safe rename of a temporary file to a common
+ * NFS-safe rename of a temporary file to a common name, designed
- * name, designed to avoid race conditions and not
+ * to avoid race conditions and not overwrite the destination if
- * overwrite the destination if it exists.
+ * it exists.
  *
- * Try to create the new filename as a hard link
+ * Try to create the new filename as a hard link to the original.
- * to the original.  Check the link count of the
+ * Check the link count of the original file to see if it worked.
- * original file to see if it worked.  (Assumes
+ * (Assumes nothing else touches our temporary file!)  If it
- * nothing else touches our temporary file!)  If
+ * worked, unlink the old filename.
- * it worked, unlink the old filename.
  */
 static int _rename(const char *old, const char *new)
 {