Merge pull request #662 from Tarsnap/comments

Fix some typos and style in comments, and add some missing comments.

Author: cperciva

tar/ccache/ccache.h

@@ -22,7 +22,7 @@ CCACHE * ccache_read(const char *);
  * the chunkification cache ${cache}, and set ${fullentry} to a non-zero
  * value iff the cache can provide at least sb->st_size bytes of the archive
  * entry.  Return a cookie which can be passed to either ccache_entry_write
- * or ccache_entry_start depending upon whether ${fullentry} is zero or not.
+ * or ccache_entry_writefile depending upon whether ${fullentry} is zero or not.
  */
 CCACHE_ENTRY * ccache_entry_lookup(CCACHE *, const char *,
     const struct stat *, TAPE_W *, int *);

tar/ccache/ccache_entry.c

@@ -199,7 +199,7 @@ callback_faketrailer(void * cookie, const uint8_t * buf, size_t buflen)
  * the chunkification cache ${cache}, and set ${fullentry} to a non-zero
  * value iff the cache can provide at least sb->st_size bytes of the archive
  * entry.  Return a cookie which can be passed to either ccache_entry_write
- * or ccache_entry_start depending upon whether ${fullentry} is zero or not.
+ * or ccache_entry_writefile depending upon whether ${fullentry} is zero or not.
  */
 CCACHE_ENTRY *
 ccache_entry_lookup(CCACHE * cache, const char * path, const struct stat * sb,

tar/glue/tape.c

@@ -12,7 +12,8 @@
 
 #include "bsdtar.h"
 
-/*
+/**
+ * tarsnap_mode_d(bsdtar):
  * Delete a tape.
  */
 void
@@ -60,7 +61,8 @@ tarsnap_mode_d(struct bsdtar *bsdtar)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_r(bsdtar):
  * Read the tape and write to stdout.
  */
 void
@@ -110,7 +112,8 @@ tarsnap_mode_r(struct bsdtar *bsdtar)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_print_stats(bsdtar):
  * Print statistics relating to an archive or set of archives.
  */
 void
@@ -171,7 +174,8 @@ tarsnap_mode_print_stats(struct bsdtar *bsdtar)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_list_archives(bsdtar, print_hashes):
  * Print the names of all the archives.
  */
 void
@@ -231,7 +235,8 @@ tarsnap_mode_list_archives(struct bsdtar *bsdtar, int print_hashes)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_fsck(bsdtar, prune, whichkey):
  * Archive set consistency check and repair.
  */
 void
@@ -265,7 +270,8 @@ tarsnap_mode_fsck(struct bsdtar *bsdtar, int prune, int whichkey)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_initialize_cachedir(bsdtar):
  * Initialize cache directory.
  */
 void
@@ -291,7 +297,8 @@ tarsnap_mode_initialize_cachedir(struct bsdtar *bsdtar)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_nuke(bsdtar):
  * Nuke all the files belonging to an archive set.
  */
 void
@@ -325,7 +332,8 @@ tarsnap_mode_nuke(struct bsdtar *bsdtar)
 	return;
 }
 
-/*
+/**
+ * tarsnap_mode_recover(bsdtar):
  * Recover an interrupted archive if one exists.
  */
 void

tar/multitape/multitape_fsck.c

@@ -176,6 +176,7 @@ phase1(uint64_t machinenum, STORAGE_D * SD, STORAGE_R * SR,
 		if ((mdat = malloc(sizeof(struct tapemetadata))) == NULL)
 			goto err2;
 
+		/* Get the next metadata file. */
 		switch (multitape_metadata_get_byhash(SR, NULL, mdat,
 		    &flist[file * 32], 1)) {
 		case -1:

tar/multitape/multitape_metadata.c

@@ -506,9 +506,12 @@ multitape_metadata_delete(STORAGE_D * S, CHUNKS_D * C,
 {
 	uint8_t hbuf[32];
 
+	/* Compute the hash of the tape name. */
 	if (crypto_hash_data(CRYPTO_KEY_HMAC_NAME,
 	    (uint8_t *)mdat->name, strlen(mdat->name), hbuf))
 		goto err0;
+
+	/* Delete the file and update the stats. */
 	if (storage_delete_file(S, 'm', hbuf))
 		goto err0;
 	chunks_delete_extrastats(C, mdat->metadatalen);

tar/multitape/multitape_metaindex.c

@@ -38,7 +38,10 @@ multitape_metaindex_fragname(const uint8_t namehash[32], uint32_t fragnum,
 {
 	uint8_t fragnum_le[4];
 
+	/* Use a platform-agnostic format for fragnum. */
 	le32enc(fragnum_le, fragnum);
+
+	/* SHA256(namehash || fragnum). */
 	if (crypto_hash_data_2(CRYPTO_KEY_HMAC_SHA256, namehash, 32,
 	    fragnum_le, 4, fraghash)) {
 		warn0("Programmer error: "
@@ -90,19 +93,21 @@ multitape_metaindex_put(STORAGE_W * S, CHUNKS_W * C,
 	if ((p = buf = malloc(buflen)) == NULL)
 		goto err0;
 
-	/* Copy values into buffer. */
+	/* Copy the header index into the buffer. */
 	le32enc(p, (uint32_t)mind->hindexlen);
 	p += 4;
 	if (mind->hindexlen > 0)
 		memcpy(p, mind->hindex, mind->hindexlen);
 	p += mind->hindexlen;
 
+	/* Copy the chunk index into the buffer. */
 	le32enc(p, (uint32_t)mind->cindexlen);
 	p += 4;
 	if (mind->cindexlen > 0)
 		memcpy(p, mind->cindex, mind->cindexlen);
 	p += mind->cindexlen;
 
+	/* Copy the trailer index into the buffer. */
 	le32enc(p, (uint32_t)mind->tindexlen);
 	p += 4;
 	if (mind->tindexlen > 0)
@@ -231,8 +236,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->hindexlen)
 		goto corrupt0;
+
+	/* Copy the header index into a new buffer. */
 	if (((mind->hindex = malloc(mind->hindexlen)) == NULL) &&
 	    (mind->hindexlen > 0))
 		goto err1;
@@ -248,8 +256,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->cindexlen)
 		goto corrupt1;
+
+	/* Copy the chunk index into a new buffer. */
 	if (((mind->cindex = malloc(mind->cindexlen)) == NULL) &&
 	    (mind->cindexlen > 0))
 		goto err2;
@@ -265,8 +276,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->tindexlen)
 		goto corrupt2;
+
+	/* Copy the trailer index into a new buffer. */
 	if (((mind->tindex = malloc(mind->tindexlen)) == NULL) &&
 	    (mind->tindexlen > 0))
 		goto err3;
@@ -275,6 +289,7 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += mind->tindexlen;
 	buflen -= mind->tindexlen;
 
+	/* Sanity check. */
 	if (buflen != 0)
 		goto corrupt3;
 
@@ -331,6 +346,7 @@ multitape_metaindex_free(struct tapemetaindex * mind)
 	if (mind == NULL)
 		return;
 
+	/* Clean up. */
 	free(mind->tindex);
 	free(mind->cindex);
 	free(mind->hindex);
@@ -351,6 +367,7 @@ multitape_metaindex_delete(STORAGE_D * S, CHUNKS_D * C,
 	size_t fraglen;
 	uint8_t fraghash[32];
 
+	/* Compute the hash of the tape name. */
 	if (crypto_hash_data(CRYPTO_KEY_HMAC_NAME,
 	    (uint8_t *)mdat->name, strlen(mdat->name), hbuf))
 		goto err0;

tar/multitape/multitape_read.c

@@ -127,10 +127,12 @@ stream_get_chunk(struct stream * S, const uint8_t ** buf, size_t * clen,
 
 	/* Skip part of the current chunk if appropriate. */
 	if (S->skiplen) {
+		/* How many bytes should we skip? */
 		skip = (off_t)(S->chunklen - S->chunkpos);
 		if (skip > S->skiplen)
 			skip = S->skiplen;
 
+		/* Skip bytes. */
 		S->skiplen -= skip;
 		S->chunkpos += (size_t)skip;
 	}
@@ -377,11 +379,13 @@ readtape_read(TAPE_R * d, const void ** buffer)
 			continue;
 		}
 
+		/* Read data. */
 		if (stream_get_chunk(readstream, buf, &clen, d->C))
 			goto err0;
 		if ((off_t)clen > *readmaxlen)
 			clen = (size_t)(*readmaxlen);
 
+		/* Update position and length. */
 		readstream->chunkpos += clen;
 		*readmaxlen -= clen;
 

tar/multitape/multitape_stats.c

@@ -401,6 +401,7 @@ statstape_print(TAPE_S * d, const char * tapename, const char * csv_filename,
 		goto err0;
 	}
 
+	/* Compute statistics. */
 	if (multitape_chunkiter_tmd(d->SR, d->C, &tmd,
 	    callback_print, d->C, 0))
 		goto err2;

tar/multitape/multitape_write.c

@@ -1054,6 +1054,7 @@ writetape_free(TAPE_W * d)
 	if (d == NULL)
 		return;
 
+	/* Clean up. */
 	chunks_write_free(d->C);
 	storage_write_free(d->S);
 	if ((d->lockfd != -1) && close(d->lockfd))