Cleanup and improve source code comments

Global review, which includes the following changes to try to increase
consistency, update and improve the source code comments:

 - Spelling fixes.
 - Use American English forms.
 - Uppercase NULL, NUL and ASCII.
 - Use “Note: ” instead of the slightly cryptic “NB: ” form.
 - Write comments as proper sentences, including capitalizations and
   ending dots.
 - Move comments before the code, function or variable they refer to.
 - Move general function comments outside the body.
 - Convert function and variable description comments to doxygen.
 - Use one space before dot, exclamation and question marks.
 - Use ‘’ or “” instead of `' style quoting.
 - Remove author names from comments, already visible from “git blame”.
 - Mark strings for translators with “TRANSLATORS: ”.
 - Remove useless or outdated comments.
 - Fix comment indentation.
 - Standardize comment format:

   /* Short text comment. */

   /* Long text,
    * comment. */

   /*
    * Section text.
    */

3 files changed, 27 insertions, 21 deletions

diff --git a/dpkg-split/dpkg-split.h b/dpkg-split/dpkg-split.h
index 5d102ea17..4d1280c3e 100644
--- a/dpkg-split/dpkg-split.h
+++ b/dpkg-split/dpkg-split.h
@@ -36,17 +36,18 @@ struct partinfo {
   unsigned long maxpartlen;
   unsigned long thispartoffset;
   size_t thispartlen;
-  size_t headerlen; /* size of header in part file */
+  /* Size of header in part file. */
+  size_t headerlen;
   off_t filesize;
 };
 
 struct partqueue {
   struct partqueue *nextinqueue;
+
+  /* Only fields filename, md5sum, maxpartlen, thispartn, maxpartn
+   * are valid; the rest are NULL. If the file is not named correctly
+   * to be a part file md5sum is NULL too and the numbers are zero. */
   struct partinfo info;
-  /* only fields filename, md5sum, maxpartlen, thispartn, maxpartn
-   * are valid; the rest are null.  If the file is not named correctly
-   * to be a part file md5sum is null too and the numbers are zero.
-   */
 };
 
 extern struct partqueue *queue;
diff --git a/dpkg-split/info.c b/dpkg-split/info.c
index 1bb27d14f..527f1d917 100644
--- a/dpkg-split/info.c
+++ b/dpkg-split/info.c
@@ -77,8 +77,13 @@ static char *nextline(char **ripp, const char *fn, const char *what) {
   return rip;
 }
 
+/**
+ * Read a deb-split part archive.
+ *
+ * @return Part info (nfmalloc'd) if was an archive part and we read it,
+ *         NULL if it wasn't.
+ */
 struct partinfo *read_info(FILE *partfile, const char *fn, struct partinfo *ir) {
-  /* returns info (nfmalloc'd) if was an archive part and we read it, 0 if it wasn't */
   static char *readinfobuf= NULL;
   static size_t readinfobuflen= 0;
 
@@ -181,8 +186,7 @@ struct partinfo *read_info(FILE *partfile, const char *fn, struct partinfo *ir)
   if (fstat(fileno(partfile),&stab)) ohshite(_("unable to fstat part file `%.250s'"),fn);
   if (S_ISREG(stab.st_mode)) {
     /* Don't do this check if it's coming from a pipe or something.  It's
-     * only an extra sanity check anyway.
-     */
+     * only an extra sanity check anyway. */
     if (stab.st_size < ir->filesize)
       ohshit(_("file `%.250s' is corrupt - too short"),fn);
   }
diff --git a/dpkg-split/queue.c b/dpkg-split/queue.c
index 69ac9767f..97865daf6 100644
--- a/dpkg-split/queue.c
+++ b/dpkg-split/queue.c
@@ -18,15 +18,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/*
- * Queue, in /var/lib/dpkg/parts, is a plain directory with one
- * file per part.
- *
- * parts are named
- *  <md5sum>.<maxpartlen>.<thispartn>.<maxpartn>
- * all numbers in hex
- */
-
 #include <config.h>
 #include <compat.h>
 
@@ -49,6 +40,15 @@
 
 #include "dpkg-split.h"
 
+/*
+ * The queue, by default located in /var/lib/dpkg/parts/, is a plain
+ * directory with one file per part.
+ *
+ * Each part is named “<md5sum>.<maxpartlen>.<thispartn>.<maxpartn>”,
+ * with all numbers in hex.
+ */
+
+
 static bool
 decompose_filename(const char *filename, struct partqueue *pq)
 {
@@ -155,9 +155,8 @@ void do_auto(const char *const *argv) {
   }
   /* If we already have a copy of this version we ignore it and prefer the
    * new one, but we still want to delete the one in the depot, so we
-   * save its partinfo (with the filename) for later.  This also prevents
-   * us from accidentally deleting the source file.
-   */
+   * save its partinfo (with the filename) for later. This also prevents
+   * us from accidentally deleting the source file. */
   otherthispart= partlist[refi->thispartn-1];
   partlist[refi->thispartn-1]= refi;
   for (j=refi->maxpartn-1; j>=0 && partlist[j]; j--);
@@ -258,7 +257,9 @@ void do_queue(const char *const *argv) {
         if (!S_ISREG(stab.st_mode))
           ohshit(_("part file `%.250s' is not a plain file"),qq->info.filename);
         bytes+= stab.st_size;
-        qq->info.md5sum= NULL; /* don't find this package again */
+
+        /* Don't find this package again. */
+        qq->info.md5sum = NULL;
       }
     }
     printf(_("(total %lu bytes)\n"),bytes);