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.
    */

dpkg-deb/build.c

@@ -48,7 +48,8 @@
 
 #include "dpkg-deb.h"
 
-/* Simple structure to store information about a file.
+/**
+ * Simple structure to store information about a file.
  */
 struct file_info {
   struct file_info *next;
@@ -115,9 +116,10 @@ file_info_find_name(struct file_info *list, const char *filename)
   return NULL;
 }
 
-/*
- * Read the next filename from a filedescriptor and create a file_info struct
- * for it. If there is nothing to read return NULL.
+/**
+ * Read a filename from the file descriptor and create a file_info struct.
+ *
+ * @return A file_info struct or NULL if there is nothing to read.
  */
 static struct file_info *
 getfi(const char *root, int fd)
@@ -167,12 +169,13 @@ getfi(const char *root, int fd)
   return fi;
 }
 
-/*
+/**
  * Add a new file_info struct to a single linked list of file_info structs.
- * We perform a slight optimization to work around a `feature' in tar: tar
+ *
+ * We perform a slight optimization to work around a ‘feature’ in tar: tar
  * always recurses into subdirectories if you list a subdirectory. So if an
  * entry is added and the previous entry in the list is its subdirectory we
- * remove the subdirectory. 
+ * remove the subdirectory.
  *
  * After a file_info struct is added to a list it may no longer be freed, we
  * assume full responsibility for its memory.
@@ -187,7 +190,7 @@ add_to_filist(struct file_info **start, struct file_info **end,
     *end=(*end)->next=fi;
 }
 
-/*
+/**
  * Free the memory for all entries in a list of file_info structs.
  */
 static void
@@ -201,7 +204,8 @@ free_filist(struct file_info *fi)
   }
 }
 
-/* Overly complex function that builds a .deb file
+/**
+ * Overly complex function that builds a .deb file.
  */
 void do_build(const char *const *argv) {
   static const char *const maintainerscripts[]= {
@@ -222,8 +226,8 @@ void do_build(const char *const *argv) {
   struct file_info *fi;
   struct file_info *symlist = NULL;
   struct file_info *symlist_end = NULL;
-  
-/* Decode our arguments */
+
+  /* Decode our arguments. */
   directory = *argv++;
   if (!directory)
     badusage(_("--%s needs a <directory> argument"), cipaction->olong);
@@ -247,8 +251,7 @@ void do_build(const char *const *argv) {
     debar= m;
   }
     
-  /* Perform some sanity checks on the to-be-build package.
-   */
+  /* Perform some sanity checks on the to-be-build package. */
   if (nocheckflag) {
     if (subdir)
       ohshit(_("target is directory - cannot skip control file check"));
@@ -260,7 +263,8 @@ void do_build(const char *const *argv) {
                           sizeof(POSTINSTFILE) + sizeof(PREINSTFILE) +
                           sizeof(POSTRMFILE) + sizeof(PRERMFILE) +
                           MAXCONFFILENAME + 5);
-    /* Lets start by reading in the control-file so we can check its contents */
+    /* Let's start by reading in the control-file so we can check its
+     * contents. */
     strcpy(controlfile, directory);
     strcat(controlfile, "/" BUILDCONTROLDIR "/" CONTROLFILE);
     warns = 0;
@@ -295,7 +299,7 @@ void do_build(const char *const *argv) {
     }
     printf(_("dpkg-deb: building package `%s' in `%s'.\n"), checkedinfo->name, debar);
 
-    /* Check file permissions */
+    /* Check file permissions. */
     strcpy(controlfile, directory);
     strcat(controlfile, "/" BUILDCONTROLDIR "/");
     if (lstat(controlfile, &mscriptstab))
@@ -324,7 +328,7 @@ void do_build(const char *const *argv) {
       }
     }
 
-    /* Check if conffiles contains sane information */
+    /* Check if conffiles contains sane information. */
     strcpy(controlfile, directory);
     strcat(controlfile, "/" BUILDCONTROLDIR "/" CONFFILESFILE);
     if ((cf= fopen(controlfile,"r"))) {
@@ -384,12 +388,11 @@ void do_build(const char *const *argv) {
   m_output(stdout, _("<standard output>"));
   
   /* Now that we have verified everything its time to actually
-   * build something. Lets start by making the ar-wrapper.
-   */
+   * build something. Let's start by making the ar-wrapper. */
   if (!(ar=fopen(debar,"wb"))) ohshite(_("unable to create `%.255s'"),debar);
   if (setvbuf(ar, NULL, _IONBF, 0))
     ohshite(_("unable to unbuffer `%.255s'"), debar);
-  /* Fork a tar to package the control-section of the package */
+  /* Fork a tar to package the control-section of the package. */
   unsetenv("TAR_OPTIONS");
   m_pipe(p1);
   c1 = subproc_fork();
@@ -402,20 +405,19 @@ void do_build(const char *const *argv) {
     ohshite(_("unable to execute %s (%s)"), "tar -cf", TAR);
   }
   close(p1[1]);
-  /* Create a temporary file to store the control data in. Immediately unlink
-   * our temporary file so others can't mess with it.
-   */
+  /* Create a temporary file to store the control data in. Immediately
+   * unlink our temporary file so others can't mess with it. */
   tfbuf = path_make_temp_template("dpkg-deb");
   gzfd = mkstemp(tfbuf);
   if (gzfd == -1)
     ohshite(_("failed to make temporary file (%s)"), _("control member"));
-  /* make sure it's gone, the fd will remain until we close it */
+  /* Make sure it's gone, the fd will remain until we close it. */
   if (unlink(tfbuf))
     ohshit(_("failed to unlink temporary file (%s), %s"), _("control member"),
            tfbuf);
   free(tfbuf);
 
-  /* And run gzip to compress our control archive */
+  /* And run gzip to compress our control archive. */
   c2 = subproc_fork();
   if (!c2) {
     m_dup2(p1[0],0); m_dup2(gzfd,1); close(p1[0]); close(gzfd);
@@ -428,9 +430,8 @@ void do_build(const char *const *argv) {
   if (lseek(gzfd, 0, SEEK_SET))
     ohshite(_("failed to rewind temporary file (%s)"), _("control member"));
 
-  /* We have our first file for the ar-archive. Write a header for it to the
-   * package and insert it.
-   */
+  /* We have our first file for the ar-archive. Write a header for it
+   * to the package and insert it. */
   if (oldformatflag) {
     if (fstat(gzfd, &controlstab))
       ohshite(_("failed to stat temporary file (%s)"), _("control member"));
@@ -455,14 +456,13 @@ void do_build(const char *const *argv) {
     gzfd = mkstemp(tfbuf);
     if (gzfd == -1)
       ohshite(_("failed to make temporary file (%s)"), _("data member"));
-    /* make sure it's gone, the fd will remain until we close it */
+    /* Make sure it's gone, the fd will remain until we close it. */
     if (unlink(tfbuf))
       ohshit(_("failed to unlink temporary file (%s), %s"), _("data member"),
              tfbuf);
     free(tfbuf);
   }
-  /* Fork off a tar. We will feed it a list of filenames on stdin later.
-   */
+  /* Fork off a tar. We will feed it a list of filenames on stdin later. */
   m_pipe(p1);
   m_pipe(p2);
   c1 = subproc_fork();
@@ -475,7 +475,7 @@ void do_build(const char *const *argv) {
   }
   close(p1[0]);
   close(p2[1]);
-  /* Of course we should not forget to compress the archive as well.. */
+  /* Of course we should not forget to compress the archive as well. */
   c2 = subproc_fork();
   if (!c2) {
     close(p1[1]);
@@ -484,10 +484,9 @@ void do_build(const char *const *argv) {
     compress_filter(compressor, 0, 1, compress_level, _("data member"));
   }
   close(p2[0]);
-  /* All the pipes are set, now lets run find, and start feeding
-   * filenames to tar.
-   */
 
+  /* All the pipes are set, now lets run find, and start feeding
+   * filenames to tar. */
   m_pipe(p3);
   c3 = subproc_fork();
   if (!c3) {
@@ -499,8 +498,7 @@ void do_build(const char *const *argv) {
   }
   close(p3[1]);
   /* We need to reorder the files so we can make sure that symlinks
-   * will not appear before their target.
-   */
+   * will not appear before their target. */
   while ((fi=getfi(directory, p3[0]))!=NULL)
     if (S_ISLNK(fi->st.st_mode))
       add_to_filist(&symlist, &symlist_end, fi);
@@ -516,12 +514,12 @@ void do_build(const char *const *argv) {
   for (fi= symlist;fi;fi= fi->next)
     if (write(p1[1], fi->fn, strlen(fi->fn)+1) == -1)
       ohshite(_("failed to write filename to tar pipe (%s)"), _("data member"));
-  /* All done, clean up wait for tar and gzip to finish their job */
+  /* All done, clean up wait for tar and gzip to finish their job. */
   close(p1[1]);
   free_filist(symlist);
   subproc_wait_check(c2, _("<compress> from tar -cf"), 0);
   subproc_wait_check(c1, "tar -cf", 0);
-  /* Okay, we have data.tar.gz as well now, add it to the ar wrapper */
+  /* Okay, we have data.tar as well now, add it to the ar wrapper. */
   if (!oldformatflag) {
     char datamember[16 + 1];
 

dpkg-deb/extract.c

@@ -192,9 +192,8 @@ void extracthalf(const char *debar, const char *directory,
 
         header_done = true;
       } else if (arh.ar_name[0] == '_') {
-          /* Members with `_' are noncritical, and if we don't understand them
-           * we skip them.
-           */
+        /* Members with ‘_’ are noncritical, and if we don't understand
+         * them we skip them. */
         fd_null_copy(arfd, memberlen + (memberlen & 1),
                      _("skipped archive member data from %s"), debar);
       } else {
@@ -224,7 +223,8 @@ void extracthalf(const char *debar, const char *directory,
           fd_null_copy(arfd, memberlen + (memberlen & 1),
                        _("skipped archive member data from %s"), debar);
         } else {
-          break; /* Yes ! - found it. */
+          /* Yes! - found it. */
+          break;
         }
       }
     }

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;

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);
   }

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);

dselect/pkgdisplay.cc

@@ -39,10 +39,11 @@ const char
 			    N_("remove"), 
 			    N_("purge"),
 			    0 },
-/* WTA: the space is a trick to work around gettext which uses the empty
- * string to store information about the translation. DO NOT CHANGE
- * THAT IN A TRANSLATION! The code really relies on that being a single space.
- */
+
+  /* TRANSLATORS: The space is a trick to work around gettext which uses
+   * the empty string to store information about the translation. DO NOT
+   * CHANGE THAT IN A TRANSLATION! The code really relies on that being
+   * a single space. */
   *const eflagstrings[]=   { N_(" "), 
 			     N_("REINSTALL"), 
 			     0 },

lib/dpkg/database.c

@@ -29,12 +29,11 @@
 #include <dpkg/dpkg.h>
 #include <dpkg/dpkg-db.h>
 
+/* This must always be a prime for optimal performance.
+ * With 4093 buckets, we glean a 20% speedup, for 8191 buckets
+ * we get 23%. The nominal increase in memory usage is a mere
+ * sizeof(void *) * 8063 (i.e. less than 32 KiB on 32bit systems). */
 #define BINS 8191
- /* This must always be a prime for optimal performance.
-  * With 4093 buckets, we glean a 20% speedup, for 8191 buckets
-  * we get 23%. The nominal increase in memory usage is a mere
-  * sizeof(void*)*8063 (I.E. less than 32KB on 32bit systems)
-  */
 
 static struct pkginfo *bins[BINS];
 static int npackages;
@@ -42,10 +41,11 @@ static int npackages;
 #define FNV_offset_basis 2166136261ul
 #define FNV_mixing_prime 16777619ul
 
-/* Fowler/Noll/Vo -- simple string hash.
- * For more info, see http://www.isthe.com/chongo/tech/comp/fnv/index.html
- * */
-
+/**
+ * Fowler/Noll/Vo -- simple string hash.
+ *
+ * For more info, see <http://www.isthe.com/chongo/tech/comp/fnv/index.html>.
+ */
 static unsigned int hash(const char *name) {
   register unsigned int h = FNV_offset_basis;
   register unsigned int p = FNV_mixing_prime;
@@ -96,13 +96,15 @@ pkg_perfile_blank(struct pkginfoperfile *pifp)
 
 static int nes(const char *s) { return s && *s; }
 
+/**
+ * Check if a pkg is informative.
+ *
+ * Used by dselect and dpkg query options as an aid to decide whether to
+ * display things, and by dump to decide whether to write them out.
+ */
 bool
 pkg_is_informative(struct pkginfo *pkg, struct pkginfoperfile *info)
 {
-  /* Used by dselect and dpkg query options as an aid to decide
-   * whether to display things, and by dump to decide whether to write them
-   * out.
-   */
   if (info == &pkg->installed &&
       (pkg->want != want_unknown ||
        pkg->eflag != eflag_ok ||

lib/dpkg/dbmodify.c

@@ -224,7 +224,7 @@ modstatdb_init(const char *admindir, enum modstatdb_rw readwritereq)
   case msdbrw_needsuperuserlockonly:
     if (getuid() || geteuid())
       ohshit(_("requested operation requires superuser privilege"));
-    /* fall through */
+    /* Fall through. */
   case msdbrw_write: case msdbrw_writeifposs:
     if (access(admindir, W_OK)) {
       if (errno != EACCES)
@@ -276,7 +276,8 @@ void modstatdb_checkpoint(void) {
   
   for (i=0; i<nextupdate; i++) {
     sprintf(updatefnrest, IMPORTANTFMT, i);
-    assert(strlen(updatefnrest)<=IMPORTANTMAXLEN); /* or we've made a real mess */
+    /* Have we made a real mess? */
+    assert(strlen(updatefnrest) <= IMPORTANTMAXLEN);
     if (unlink(updatefnbuf))
       ohshite(_("failed to remove my own update file %.255s"),updatefnbuf);
   }
@@ -292,11 +293,11 @@ void modstatdb_shutdown(void) {
   case msdbrw_write:
     modstatdb_checkpoint();
     writedb(availablefile,1,0);
-    /* tidy up a bit, but don't worry too much about failure */
+    /* Tidy up a bit, but don't worry too much about failure. */
     fclose(importanttmp);
     unlink(importanttmpfile);
     varbuf_destroy(&uvb);
-    /* fall through */
+    /* Fall through. */
   case msdbrw_needsuperuserlockonly:
     modstatdb_unlock();
   default:
@@ -347,7 +348,8 @@ modstatdb_note_core(struct pkginfo *pkg)
   createimptmp();
 }
 
-/* Note: If anyone wants to set some triggers-pending, they must also
+/*
+ * Note: If anyone wants to set some triggers-pending, they must also
  * set status appropriately, or we will undo it. That is, it is legal
  * to call this when pkg->status and pkg->trigpend_head disagree and
  * in that case pkg->status takes precedence and pkg->trigpend_head
@@ -359,8 +361,7 @@ void modstatdb_note(struct pkginfo *pkg) {
   onerr_abort++;
 
   /* Clear pending triggers here so that only code that sets the status
-   * to interesting (for triggers) values has to care about triggers.
-   */
+   * to interesting (for triggers) values has to care about triggers. */
   if (pkg->status != stat_triggerspending &&
       pkg->status != stat_triggersawaited)
     pkg->trigpend_head = NULL;
@@ -380,12 +381,11 @@ void modstatdb_note(struct pkginfo *pkg) {
 
   if (!pkg->trigpend_head && pkg->othertrigaw_head) {
     /* Automatically remove us from other packages' Triggers-Awaited.
-     * We do this last because we want to maximise our chances of
+     * We do this last because we want to maximize our chances of
      * successfully recording the status of the package we were
      * pointed at by our caller, although there is some risk of
      * leaving us in a slightly odd situation which is cleared up
-     * by the trigger handling logic in deppossi_ok_found.
-     */
+     * by the trigger handling logic in deppossi_ok_found. */
     trig_clear_awaiters(pkg);
   }
 

lib/dpkg/dpkg-db.h

@@ -101,10 +101,12 @@ struct filedetails {
   const char *md5sum;
 };
 
-struct pkginfoperfile { /* pif */
+/* pif */
+struct pkginfoperfile {
   struct dependency *depends;
   struct deppossi *depended;
-  bool essential; /* The ‘essential’ flag, true = yes, false = no (absent). */
+  /* The ‘essential’ flag, true = yes, false = no (absent). */
+  bool essential;
   const char *description;
   const char *maintainer;
   const char *source;
@@ -117,18 +119,22 @@ struct pkginfoperfile { /* pif */
   struct arbitraryfield *arbs;
 };
 
+/**
+ * Node indicates that parent's Triggers-Pending mentions name.
+ *
+ * Note: These nodes do double duty: after they're removed from a package's
+ * trigpend list, references may be preserved by the trigger cycle checker
+ * (see trigproc.c).
+ */
 struct trigpend {
-  /* Node indicates that parent's Triggers-Pending mentions name. */
-  /* NB that these nodes do double duty: after they're removed from
-   * a package's trigpend list, references may be preserved by the
-   * trigger cycle checker (see trigproc.c).
-   */
   struct trigpend *next;
   const char *name;
 };
 
+/**
+ * Node indicates that aw's Triggers-Awaited mentions pend.
+ */
 struct trigaw {
-  /* Node indicates that aw's Triggers-Awaited mentions pend. */
   struct pkginfo *aw, *pend;
   struct trigaw *samepend_next;
   struct {
@@ -136,20 +142,23 @@ struct trigaw {
   } sameaw;
 };
 
-struct perpackagestate; /* dselect and dpkg have different versions of this */
+/* Note: dselect and dpkg have different versions of this. */
+struct perpackagestate;
 
-struct pkginfo { /* pig */
+/* pig */
+struct pkginfo {
   struct pkginfo *next;
   const char *name;
   enum pkgwant {
     want_unknown, want_install, want_hold, want_deinstall, want_purge,
-    want_sentinel /* Not allowed except as special sentinel value
-                     in some places */
+    /* Not allowed except as special sentinel value in some places. */
+    want_sentinel,
   } want;
+  /* The error flag bitmask. */
   enum pkgeflag {
     eflag_ok		= 0,
     eflag_reinstreq	= 1,
-  } eflag; /* Bitmask. */
+  } eflag;
   enum pkgstatus {
     stat_notinstalled,
     stat_configfiles,
@@ -195,7 +204,7 @@ enum modstatdb_rw {
   msdbrw_write/*s*/, msdbrw_needsuperuser,
   /* Now some optional flags: */
   msdbrw_flagsmask= ~077,
-  /* flags start at 0100 */
+  /* Flags start at 0100. */
   msdbrw_noavail= 0100,
 };
 
@@ -231,14 +240,18 @@ void hashreport(FILE*);
 /*** from parse.c ***/
 
 enum parsedbflags {
-  pdb_recordavailable   =001, /* Store in `available' in-core structures, not `status' */
-  pdb_rejectstatus      =002, /* Throw up an error if `Status' encountered             */
-  pdb_weakclassification=004, /* Ignore priority/section info if we already have any   */
-  pdb_ignorefiles       =010, /* Ignore files info if we already have them             */
+  /* Store in ‘available’ in-core structures, not ‘status’. */
+  pdb_recordavailable = 001,
+  /* Throw up an error if ‘Status’ encountered. */
+  pdb_rejectstatus = 002,
+  /* Ignore priority/section info if we already have any. */
+  pdb_weakclassification = 004,
+  /* Ignore files info if we already have them. */
+  pdb_ignorefiles = 010,
   /* Ignore packages with older versions already read. */
-  pdb_ignoreolder       =020,
+  pdb_ignoreolder = 020,
   /* Perform laxer parsing, used to transition to stricter parsing. */
-  pdb_lax_parser        =040,
+  pdb_lax_parser = 040,
 };
 
 const char *pkg_name_is_illegal(const char *p, const char **ep);
@@ -275,9 +288,10 @@ void writerecord(FILE*, const char*,
 
 void writedb(const char *filename, bool available, bool mustsync);
 
+/* Note: The varbufs must have been initialized and will not be
+ * NUL-terminated. */
 void varbufrecord(struct varbuf*, const struct pkginfo*, const struct pkginfoperfile*);
 void varbufdependency(struct varbuf *vb, struct dependency *dep);
-  /* NB THE VARBUF MUST HAVE BEEN INITIALISED AND WILL NOT BE NULL-TERMINATED */
 
 /*** from vercmp.c ***/
 

lib/dpkg/dpkg.h

@@ -108,7 +108,8 @@ DPKG_BEGIN_DECLS
 
 #define standard_startup() do { \
   push_error_context(); \
-  umask(022); /* Make sure all our status databases are readable. */\
+  /* Make sure all our status databases are readable. */ \
+  umask(022); \
 } while (0)
 
 #define standard_shutdown() do { \

lib/dpkg/dump.c

@@ -19,7 +19,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/* FIXME: don't write uninteresting packages */
+/* FIXME: Don't write uninteresting packages. */
+
 #include <config.h>
 #include <compat.h>
 
@@ -55,7 +56,6 @@ void w_name(struct varbuf *vb,
 void w_version(struct varbuf *vb,
                const struct pkginfo *pigp, const struct pkginfoperfile *pifp,
                enum fwriteflags flags, const struct fieldinfo *fip) {
-  /* Epoch and revision information is printed in version field too. */
   if (!informativeversion(&pifp->version)) return;
   if (flags&fw_printheader)
     varbufaddstr(vb,"Version: ");

lib/dpkg/ehandle.c

@@ -33,18 +33,18 @@
 #include <dpkg/i18n.h>
 #include <dpkg/ehandle.h>
 
-static const char *errmsg; /* points to errmsgbuf or malloc'd */
-static char errmsgbuf[4096];
-/* 6x255 for inserted strings (%.255s &c in fmt; also %s with limited length arg)
+/* Points to errmsgbuf or malloc'd. */
+static const char *errmsg;
+
+/* 6x255 for inserted strings (%.255s &c in fmt; and %s with limited length arg)
  * 1x255 for constant text
  * 1x255 for strerror()
- * same again just in case.
- */
+ * same again just in case. */
+static char errmsgbuf[4096];
 
 /* Incremented when we do some kind of generally necessary operation,
  * so that loops &c know to quit if we take an error exit. Decremented
- * again afterwards.
- */
+ * again afterwards. */
 volatile int onerr_abort = 0;
 
 #define NCALLS 2
@@ -92,8 +92,7 @@ run_error_handler(void)
      * and trying to do so would most probably get us here again. That's
      * why we will not try to do any error unwinding either. We'll just
      * abort. Hopefully the user can fix the situation (out of disk, out
-     * of memory, etc).
-     */
+     * of memory, etc). */
     fprintf(stderr, _("%s: unrecoverable fatal error, aborting:\n %s\n"),
             thisname, errmsg);
     exit(2);
@@ -251,13 +250,16 @@ pop_error_context(int flagset)
   free(tecp);
 }
 
+/**
+ * Push an error cleanup checkpoint.
+ *
+ * This will arrange that when pop_error_context() is called, all previous
+ * cleanups will be executed with
+ *   flagset = (original_flagset & mask) | value
+ * where original_flagset is the argument to pop_error_context() (as
+ * modified by any checkpoint which was pushed later).
+ */
 void push_checkpoint(int mask, int value) {
-  /* This will arrange that when pop_error_context() is called,
-   * all previous cleanups will be executed with
-   *  flagset= (original_flagset & mask) | value
-   * where original_flagset is the argument to pop_error_context()
-   * (as modified by any checkpoint which was pushed later).
-   */
   struct cleanup_entry *cep;
   int i;
   

lib/dpkg/ehandle.h

@@ -30,7 +30,8 @@
 
 DPKG_BEGIN_DECLS
 
-extern const char thisname[]; /* defined separately in each program */
+/* Defined separately in each program. */
+extern const char thisname[];
 
 extern volatile int onerr_abort;
 

lib/dpkg/fields.c

@@ -210,6 +210,9 @@ void f_configversion(struct pkginfo *pigp, struct pkginfoperfile *pifp,
 
 }
 
+/*
+ * The code in f_conffiles ensures that value[-1] == ' ', which is helpful.
+ */
 static void conffvalue_lastword(const char *value, const char *from,
                                 const char *endent,
                                 const char **word_start_r, int *word_len_r,
@@ -217,7 +220,6 @@ static void conffvalue_lastword(const char *value, const char *from,
                                 struct parsedb_state *ps,
                                 struct pkginfo *pigp)
 {
-  /* the code in f_conffiles ensures that value[-1]==' ', which is helpful */
   const char *lastspc;
   
   if (from <= value+1) goto malformed;
@@ -297,20 +299,26 @@ void f_dependency(struct pkginfo *pigp, struct pkginfoperfile *pifp,
   struct dependency *dyp, **ldypp;
   struct deppossi *dop, **ldopp;
 
-  if (!*value) return; /* empty fields are ignored */
+  /* Empty fields are ignored. */
+  if (!*value)
+    return;
   p= value;
   ldypp= &pifp->depends; while (*ldypp) ldypp= &(*ldypp)->next;
-  for (;;) { /* loop creating new struct dependency's */
+
+   /* Loop creating new struct dependency's. */
+  for (;;) {
     dyp= nfmalloc(sizeof(struct dependency));
-    dyp->up= NULL; /* Set this to zero for now, as we don't know what our real
-                 * struct pkginfo address (in the database) is going to be yet.
-                 */
+    /* Set this to NULL for now, as we don't know what our real
+     * struct pkginfo address (in the database) is going to be yet. */
+    dyp->up = NULL;
     dyp->next= NULL; *ldypp= dyp; ldypp= &dyp->next;
     dyp->list= NULL; ldopp= &dyp->list;
     dyp->type= fip->integer;
-    for (;;) { /* loop creating new struct deppossi's */
+
+    /* Loop creating new struct deppossi's. */
+    for (;;) {
       depnamestart= p;
-/* skip over package name characters */
+      /* Skip over package name characters. */
       while (*p && !isspace(*p) && *p != '(' && *p != ',' && *p != '|') {
 	p++;
       }
@@ -342,9 +350,12 @@ void f_dependency(struct pkginfo *pigp, struct pkginfoperfile *pifp,
       dop->rev_prev = NULL;
 
       dop->cyclebreak = false;
-/* skip whitespace after packagename */
+
+      /* Skip whitespace after package name. */
       while (isspace(*p)) p++;
-      if (*p == '(') {			/* if we have a versioned relation */
+
+      /* See if we have a versioned relation. */
+      if (*p == '(') {
         p++; while (isspace(*p)) p++;
         c1= *p;
         if (c1 == '<' || c1 == '>') {
@@ -391,7 +402,7 @@ void f_dependency(struct pkginfo *pigp, struct pkginfoperfile *pifp,
                        "suggest adding a space"),
                      fip->name, depname.buf);
         }
-/* skip spaces between the relation and the version */
+        /* Skip spaces between the relation and the version. */
         while (isspace(*p)) p++;
 
 	versionstart= p;

lib/dpkg/file.c

@@ -34,6 +34,12 @@
 #include <dpkg/i18n.h>
 #include <dpkg/file.h>
 
+/**
+ * Copy file ownership and permissions from one file to another.
+ *
+ * @param src The source filename.
+ * @param dst The destination filename.
+ */
 void
 file_copy_perms(const char *src, const char *dst)
 {
@@ -106,8 +112,15 @@ file_is_locked(int lockfd, const char *filename)
 		return false;
 }
 
-/* lockfd must be allocated statically as its addresses is passed to
- * a cleanup handler. */
+/**
+ * Lock a file.
+ *
+ * @param lockfd The pointer to the lock file descriptor. It must be allocated
+ *        statically as its addresses is passed to a cleanup handler.
+ * @param flags The lock flags specifiying what type of locking to perform.
+ * @param filename The name of the file to lock.
+ * @param desc The description of the file to lock.
+ */
 void
 file_lock(int *lockfd, enum file_lock_flags flags, const char *filename,
           const char *desc)

lib/dpkg/file.h

@@ -36,9 +36,6 @@ struct file_stat {
 	time_t mtime;
 };
 
-/*
- * Copy file ownership and permissions from one file to another.
- */
 void file_copy_perms(const char *src, const char *dst);
 
 enum file_lock_flags {

lib/dpkg/mlib.c

@@ -1,6 +1,6 @@
 /*
  * libdpkg - Debian packaging suite library routines
- * mlib.c - `must' library: routines will succeed or longjmp
+ * mlib.c - ‘must’ library: routines will succeed or longjmp
  *
  * Copyright © 1994,1995 Ian Jackson <ian@chiark.greenend.org.uk>
  *

lib/dpkg/myopt.h

@@ -30,7 +30,14 @@ typedef void void_func(void);
 struct cmdinfo {
   const char *olong;
   char oshort;
-  int takesvalue; /* 0 = normal   1 = standard value   2 = option string cont */
+
+  /*
+   * 0 = Normal				(-o, --option)
+   * 1 = Standard value			(-o=value, --option=value or
+   *					 -o value, --option value)
+   * 2 = Option string continued	(--option-value)
+   */
+  int takesvalue;
   int *iassignto;
   const char **sassignto;
   void (*call)(const struct cmdinfo*, const char *value);

lib/dpkg/nfmalloc.c

@@ -35,7 +35,7 @@
 static struct obstack db_obs;
 static bool dbobs_init = false;
 
-/* We use lots of mem, so use a large chunk */
+/* We use lots of mem, so use a large chunk. */
 #define CHUNK_SIZE 8192
 
 #define OBSTACK_INIT if (!dbobs_init) { nfobstack_init(); }

lib/dpkg/parse.c

@@ -44,7 +44,7 @@
 #include <dpkg/buffer.h>
 
 const struct fieldinfo fieldinfos[]= {
-  /* NB: capitalisation of these strings is important. */
+  /* Note: Capitalization of field name strings is important. */
   { "Package",          f_name,            w_name                                     },
   { "Essential",        f_boolean,         w_booleandefno,   PKGIFPOFF(essential)     },
   { "Status",           f_status,          w_status                                   },
@@ -77,16 +77,18 @@ const struct fieldinfo fieldinfos[]= {
   { "Triggers-Pending", f_trigpend,        w_trigpend                                 },
   { "Triggers-Awaited", f_trigaw,          w_trigaw                                   },
   /* Note that aliases are added to the nicknames table in parsehelp.c. */
-  {  NULL   /* sentinel - tells code that list is ended */                               }
+  {  NULL                                                                             }
 };
 
+/**
+ * Parse an RFC-822 style file.
+ *
+ * warnto, warncount and donep may be NULL.
+ * If donep is not NULL only one package's information is expected.
+ */
 int parsedb(const char *filename, enum parsedbflags flags,
             struct pkginfo **donep, int *warncount)
 {
-  /* warncount and donep may be null.
-   * If donep is not null only one package's information is expected.
-   */
-  
   static int fd;
   struct pkginfo newpig, *pigp;
   struct pkginfoperfile *newpifp, *pifp;
@@ -139,17 +141,20 @@ int parsedb(const char *filename, enum parsedbflags flags,
 #define getc_mmap(dataptr)		*dataptr++;
 #define ungetc_mmap(c, dataptr, data)	dataptr--;
 
-  for (;;) { /* loop per package */
+  /* Loop per package. */
+  for (;;) {
     memset(fieldencountered, 0, sizeof(fieldencountered));
     pkg_blank(&newpig);
 
-/* Skip adjacent new lines */
+    /* Skip adjacent new lines. */
     while(!EOF_mmap(dataptr, endptr)) {
       c= getc_mmap(dataptr); if (c!='\n' && c!=MSDOS_EOF_CHAR ) break;
       ps.lno++;
     }
     if (EOF_mmap(dataptr, endptr)) break;
-    for (;;) { /* loop per field */
+
+    /* Loop per field. */
+    for (;;) {
       fieldstart= dataptr - 1;
       while (!EOF_mmap(dataptr, endptr) && !isspace(c) && c!=':' && c!=MSDOS_EOF_CHAR)
         c= getc_mmap(dataptr);
@@ -169,7 +174,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
         parse_error(&ps, &newpig,
                     _("field name `%.*s' must be followed by colon"),
                     fieldlen, fieldstart);
-/* Skip space after ':' but before value and eol */
+      /* Skip space after ‘:’ but before value and EOL. */
       while(!EOF_mmap(dataptr, endptr)) {
         c= getc_mmap(dataptr);
         if (c == '\n' || !isspace(c)) break;
@@ -188,7 +193,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
           ps.lno++;
 	  if (EOF_mmap(dataptr, endptr)) break;
           c= getc_mmap(dataptr);
-/* Found double eol, or start of new field */
+          /* Found double EOL, or start of new field. */
           if (EOF_mmap(dataptr, endptr) || c == '\n' || !isspace(c)) break;
           ungetc_mmap(c,dataptr, data);
           c= '\n';
@@ -200,7 +205,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
         c= getc_mmap(dataptr);
       }
       valuelen= dataptr - valuestart - 1;
-/* trim ending space on value */
+      /* Trim ending space on value. */
       while (valuelen && isspace(*(valuestart+valuelen-1)))
  valuelen--;
       for (nick = nicknames;
@@ -241,7 +246,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
         *larpp= arp;
       }
       if (EOF_mmap(dataptr, endptr) || c == '\n' || c == MSDOS_EOF_CHAR) break;
-    } /* loop per field */
+    } /* Loop per field. */
     if (pdone && donep)
       parse_error(&ps, &newpig,
                   _("several package info entries found, only one allowed"));
@@ -266,10 +271,9 @@ int parsedb(const char *filename, enum parsedbflags flags,
 
     /* Check the Config-Version information:
      * If there is a Config-Version it is definitely to be used, but
-     * there shouldn't be one if the package is `installed' (in which case
+     * there shouldn't be one if the package is ‘installed’ (in which case
      * the Version and/or Revision will be copied) or if the package is
-     * `not-installed' (in which case there is no Config-Version).
-     */
+     * ‘not-installed’ (in which case there is no Config-Version). */
     if (!(flags & pdb_recordavailable)) {
       if (newpig.configversion.version) {
         if (newpig.status == stat_installed || newpig.status == stat_notinstalled)
@@ -304,8 +308,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
 
     /* FIXME: There was a bug that could make a not-installed package have
      * conffiles, so we check for them here and remove them (rather than
-     * calling it an error, which will do at some point).
-     */
+     * calling it an error, which will do at some point). */
     if (!(flags & pdb_recordavailable) &&
         newpig.status == stat_notinstalled &&
         newpifp->conffiles) {
@@ -336,8 +339,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
       continue;
 
     /* Copy the priority and section across, but don't overwrite existing
-     * values if the pdb_weakclassification flag is set.
-     */
+     * values if the pdb_weakclassification flag is set. */
     if (newpig.section && *newpig.section &&
         !((flags & pdb_weakclassification) && pigp->section && *pigp->section))
       pigp->section= newpig.section;
@@ -350,15 +352,14 @@ int parsedb(const char *filename, enum parsedbflags flags,
     /* Sort out the dependency mess. */
     copy_dependency_links(pigp,&pifp->depends,newpifp->depends,
                           (flags & pdb_recordavailable) ? 1 : 0);
-    /* Leave the `depended' pointer alone, we've just gone to such
-     * trouble to get it right :-).  The `depends' pointer in
+    /* Leave the ‘depended’ pointer alone, we've just gone to such
+     * trouble to get it right :-). The ‘depends’ pointer in
      * pifp was indeed also updated by copy_dependency_links,
      * but since the value was that from newpifp anyway there's
-     * no need to copy it back.
-     */
+     * no need to copy it back. */
     newpifp->depended= pifp->depended;
 
-    /* Copy across data */
+    /* Copy across data. */
     memcpy(pifp,newpifp,sizeof(struct pkginfoperfile));
     if (!(flags & pdb_recordavailable)) {
       pigp->want= newpig.want;
@@ -373,7 +374,7 @@ int parsedb(const char *filename, enum parsedbflags flags,
         assert(ta->aw == &newpig);
         ta->aw = pigp;
         /* ->othertrigaw_head is updated by trig_note_aw in *(pkg_db_find())
-         * rather than in newpig */
+         * rather than in newpig. */
       }
 
     } else if (!(flags & pdb_ignorefiles)) {
@@ -404,44 +405,43 @@ int parsedb(const char *filename, enum parsedbflags flags,
   return pdone;
 }
 
+/**
+ * Copy dependency links structures.
+ *
+ * This routine is used to update the ‘reverse’ dependency pointers when
+ * new ‘forwards’ information has been constructed. It first removes all
+ * the links based on the old information. The old information starts in
+ * *updateme; after much brou-ha-ha the reverse structures are created
+ * and *updateme is set to the value from newdepends.
+ *
+ * @param pkg The package we're doing this for. This is used to construct
+ *        correct uplinks.
+ * @param updateme The forwards dependency pointer that we are to update.
+ *        This starts out containing the old forwards info, which we use to
+ *        unthread the old reverse links. After we're done it is updated.
+ * @param newdepends The value that we ultimately want to have in updateme.
+ * @param available The pkginfoperfile to modify, available or installed.
+ *
+ * It is likely that the backward pointer for the package in question
+ * (‘depended’) will be updated by this routine, but this will happen by
+ * the routine traversing the dependency data structures. It doesn't need
+ * to be told where to update that; I just mention it as something that
+ * one should be cautious about.
+ */
 void copy_dependency_links(struct pkginfo *pkg,
                            struct dependency **updateme,
                            struct dependency *newdepends,
                            bool available)
 {
-  /* This routine is used to update the `reverse' dependency pointers
-   * when new `forwards' information has been constructed.  It first
-   * removes all the links based on the old information.  The old
-   * information starts in *updateme; after much brou-ha-ha
-   * the reverse structures are created and *updateme is set
-   * to the value from newdepends.
-   *
-   * Parameters are:
-   * pkg - the package we're doing this for.  This is used to
-   *       construct correct uplinks.
-   * updateme - the forwards dependency pointer that we are to
-   *            update.  This starts out containing the old forwards
-   *            info, which we use to unthread the old reverse
-   *            links.  After we're done it is updated.
-   * newdepends - the value that we ultimately want to have in
-   *              updateme.
-   * It is likely that the backward pointer for the package in
-   * question (`depended') will be updated by this routine,
-   * but this will happen by the routine traversing the dependency
-   * data structures.  It doesn't need to be told where to update
-   * that; I just mention it as something that one should be
-   * cautious about.
-   */
   struct dependency *dyp;
   struct deppossi *dop;
   struct pkginfoperfile *addtopifp;
   
-  /* Delete `backward' (`depended') links from other packages to
-   * dependencies listed in old version of this one.  We do this by
+  /* Delete ‘backward’ (‘depended’) links from other packages to
+   * dependencies listed in old version of this one. We do this by
    * going through all the dependencies in the old version of this
    * one and following them down to find which deppossi nodes to
-   * remove.
-   */
+   * remove. */
   for (dyp= *updateme; dyp; dyp= dyp->next) {
     for (dop= dyp->list; dop; dop= dop->next) {
       if (dop->rev_prev)
@@ -455,9 +455,8 @@ void copy_dependency_links(struct pkginfo *pkg,
         dop->rev_next->rev_prev = dop->rev_prev;
     }
   }
-  /* Now fill in new `ed' links from other packages to dependencies listed
-   * in new version of this one, and set our uplinks correctly.
-   */
+  /* Now fill in new ‘ed’ links from other packages to dependencies
+   * listed in new version of this one, and set our uplinks correctly. */
   for (dyp= newdepends; dyp; dyp= dyp->next) {
     dyp->up= pkg;
     for (dop= dyp->list; dop; dop= dop->next) {

lib/dpkg/parsedump.h

@@ -46,7 +46,8 @@ freadfunction f_configversion;
 freadfunction f_trigpend, f_trigaw;
 
 enum fwriteflags {
-	fw_printheader	= 001	/* print field header and trailing newline */
+	/* Print field header and trailing newline. */
+	fw_printheader = 001,
 };
 
 typedef void fwritefunction(struct varbuf*,

lib/dpkg/parsehelp.c

@@ -125,7 +125,8 @@ const struct namevalue wantinfos[] = {
 const char *
 pkg_name_is_illegal(const char *p, const char **ep)
 {
-  static const char alsoallowed[]= "-+._"; /* _ is deprecated */
+  /* FIXME: _ is deprecated, remove sometime. */
+  static const char alsoallowed[] = "-+._";
   static char buf[150];
   int c;
   
@@ -145,7 +146,7 @@ pkg_name_is_illegal(const char *p, const char **ep)
 }
 
 const struct nickname nicknames[]= {
-  /* NB: capitalisation of these strings is important. */
+  /* Note: Capitalization of these strings is important. */
   { .nick = "Recommended",      .canon = "Recommends" },
   { .nick = "Optional",         .canon = "Suggests" },
   { .nick = "Class",            .canon = "Priority" },
@@ -174,7 +175,8 @@ void varbufversion
     if (!version->epoch &&
         (!version->version || !strchr(version->version,':')) &&
         (!version->revision || !strchr(version->revision,':'))) break;
-  case vdew_always: /* FALL THROUGH */
+    /* Fall through. */
+  case vdew_always:
     varbufprintf(vb,"%lu:",version->epoch);
     break;
   default:
@@ -215,15 +217,15 @@ parseversion_lax(struct versionrevision *rversion, const char *string)
 
   if (!*string) return _("version string is empty");
 
-  /* trim leading and trailing space */
+  /* Trim leading and trailing space. */
   while (*string && isblank(*string))
     string++;
-  /* string now points to the first non-whitespace char */
+  /* String now points to the first non-whitespace char. */
   end = string;
-  /* find either the end of the string, or a whitespace char */
+  /* Find either the end of the string, or a whitespace char. */
   while (*end && !isblank(*end))
     end++;
-  /* check for extra chars after trailing space */
+  /* Check for extra chars after trailing space. */
   ptr = end;
   while (*ptr && isblank(*ptr))
     ptr++;

lib/dpkg/path.c

@@ -83,26 +83,22 @@ path_make_temp_template(const char *suffix)
 	return varbuf_detach(&template);
 }
 
-/*
- * snprintf(3) doesn't work if format contains %.<nnn>s and an argument has
- * invalid char for locale, then it returns -1.
- * ohshite() is ok, but fd_fd_copy(), which is used in tarobject(), is not
- * ok, because:
+/**
+ * Escape characters in a pathname for safe locale printing.
+ *
+ * We need to quote paths so that they do not cause problems when printing
+ * them, for example with snprintf(3) which does not work if the format
+ * string contains %s and an argument has invalid characters for the
+ * current locale, it will then return -1.
  *
- * - fd_fd_copy() == buffer_copy_TYPE() ‘lib/dpkg/buffer.h’.
- * - buffer_copy_TYPE() uses varbufvprintf(&v, desc, al); ‘lib/dpkg/buffer.c’.
- * - varbufvprintf() fails, because it calls with:
- *     fmt = "backend dpkg-deb during '%.255s'"
- *   arg may contain some invalid char, for example,
- *   «/usr/share/doc/console-tools/examples/unicode/\342\231\252\342\231\254»
- *   in console-tools.
+ * To simplify things, we just escape all 8 bit characters, instead of
+ * just invalid characters.
  *
- * In this case, if the user uses some locale which doesn't support
- * “\342\231...”, vsnprintf() always returns -1 and varbufextend() fails.
+ * @param dst The escaped destination string.
+ * @param src The source string to escape.
+ * @param n The size of the destination buffer.
  *
- * So, we need to escape invalid char, probably as in
- * ‘tar-1.13.19/lib/quotearg.c: quotearg_buffer_restyled()’
- * but here we escape all 8 bit chars, in order make it simple.
+ * @return The destination string.
  */
 char *
 path_quote_filename(char *dst, const char *src, size_t n)

lib/dpkg/string.c

@@ -51,7 +51,13 @@ str_escape_fmt(char *dst, const char *src, size_t n)
 	return d;
 }
 
-/* Check and strip possible surrounding quotes in string. */
+/**
+ * Check and strip possible surrounding quotes in string.
+ *
+ * @param str The string to act on.
+ *
+ * @return A pointer to str or NULL if the quotes were unbalanced.
+ */
 char *
 str_strip_quotes(char *str)
 {

lib/dpkg/tarfn.c

@@ -54,12 +54,16 @@ struct TarHeader {
 	char GroupName[32];
 	char MajorDevice[8];
 	char MinorDevice[8];
-	char Prefix[155];	/* Only valid on ustar. */
+
+	/* Only valid on ustar. */
+	char Prefix[155];
 };
 
 static const size_t TarChecksumOffset = offsetof(struct TarHeader, Checksum);
 
-/* Octal-ASCII-to-long */
+/**
+ * Convert an ASCII octal string to a long.
+ */
 static long
 OtoL(const char *s, int size)
 {
@@ -76,7 +80,9 @@ OtoL(const char *s, int size)
 	return n;
 }
 
-/* String block to C null-terminated string */
+/**
+ * Convert a string block to C NUL-terminated string.
+ */
 static char *
 StoC(const char *s, int size)
 {

lib/dpkg/trigdeferred.h

@@ -43,14 +43,6 @@ struct trigdefmeths {
 
 void trigdef_set_methods(const struct trigdefmeths *methods);
 
-/*
- * Return values:
- *  -1  Lock ENOENT with O_CREAT (directory does not exist)
- *  -2  Unincorp empty, tduf_writeifempty unset
- *  -3  Unincorp ENOENT, tduf_writeifenoent unset
- *   1  Unincorp ENOENT, tduf_writeifenoent set   } caller must call
- *   2  ok                                        }  trigdef_update_done!
- */
 int trigdef_update_start(enum trigdef_updateflags uf, const char *admindir);
 void trigdef_update_printf(const char *format, ...) DPKG_ATTR_PRINTF(1);
 int trigdef_parse(void);

lib/dpkg/trigdeferred.l

@@ -105,6 +105,17 @@ constructfn(struct varbuf *vb, const char *dir, const char *tail)
 	varbufaddc(vb, 0);
 }
 
+/**
+ * Start processing of the triggers deferred file.
+ *
+ * @retval -1 Lock ENOENT with O_CREAT (directory does not exist).
+ * @retval -2 Unincorp empty, tduf_writeifempty unset.
+ * @retval -3 Unincorp ENOENT, tduf_writeifenoent unset.
+ * @retval  1 Unincorp ENOENT, tduf_writeifenoent set.
+ * @retval  2 Ok.
+ *
+ * For positive return values the caller must call trigdef_update_done!
+ */
 int
 trigdef_update_start(enum trigdef_updateflags uf, const char *admindir)
 {

lib/dpkg/triglib.c

@@ -55,7 +55,7 @@ trig_name_is_illegal(const char *p)
 	return NULL;
 }
 
-/*========== recording triggers ==========*/
+/*========== Recording triggers. ==========*/
 
 static char *triggersdir, *triggersfilefile, *triggersnewfilefile;
 
@@ -81,11 +81,12 @@ trig_get_filename(const char *dir, const char *filename)
 
 static struct trig_hooks trigh;
 
-/*---------- noting trigger activation in memory ----------*/
+/*---------- Noting trigger activation in memory. ----------*/
 
-/* Called via trig_*activate* et al from:
+/*
+ * Called via trig_*activate* et al from:
  *   - trig_incorporate: reading of Unincorp (explicit trigger activations)
- *   - various places: processing start (`activate' in triggers ci file)
+ *   - various places: processing start (‘activate’ in triggers ci file)
  *   - namenodetouse: file triggers during unpack / remove
  *   - deferred_configure: file triggers during config file processing
  *
@@ -94,19 +95,21 @@ static struct trig_hooks trigh;
  * recorded (how would we know?) and (b) we don't enqueue them for
  * deferred processing in this run.
  *
- * We add the trigger to Triggers-Pending first.  This makes it
+ * We add the trigger to Triggers-Pending first. This makes it
  * harder to get into the state where Triggers-Awaited for aw lists
- * pend but Triggers-Pending for pend is empty.  (See also the
+ * pend but Triggers-Pending for pend is empty. (See also the
  * comment in deppossi_ok_found regarding this situation.)
  */
 
-/* aw might be NULL, and trig is not copied! */
+/*
+ * aw might be NULL.
+ * trig is not copied!
+ */
 static void
 trig_record_activation(struct pkginfo *pend, struct pkginfo *aw, const char *trig)
 {
 	if (pend->status < stat_triggersawaited)
-		/* Not interested then. */
-		return;
+		return; /* Not interested then. */
 
 	if (trig_note_pend(pend, trig))
 		modstatdb_note_ifwrite(pend);
@@ -122,9 +125,13 @@ trig_record_activation(struct pkginfo *pend, struct pkginfo *aw, const char *tri
 		}
 }
 
-/* NB that this is also called from fields.c where *pend is a temporary! */
+/*
+ * Note: This is also called from fields.c where *pend is a temporary!
+ *
+ * trig is not copied!
+ */
 bool
-trig_note_pend_core(struct pkginfo *pend, const char *trig /*not copied!*/)
+trig_note_pend_core(struct pkginfo *pend, const char *trig)
 {
 	struct trigpend *tp;
 
@@ -140,9 +147,14 @@ trig_note_pend_core(struct pkginfo *pend, const char *trig /*not copied!*/)
 	return true;
 }
 
-/* Returns: true for done, false for already noted. */
+/*
+ * trig is not copied!
+ *
+ * @retval true  For done.
+ * @retval false For already noted.
+ */
 bool
-trig_note_pend(struct pkginfo *pend, const char *trig /*not copied!*/)
+trig_note_pend(struct pkginfo *pend, const char *trig)
 {
 	if (!trig_note_pend_core(pend, trig))
 		return false;
@@ -153,9 +165,13 @@ trig_note_pend(struct pkginfo *pend, const char *trig /*not copied!*/)
 	return true;
 }
 
-/* Returns: true for done, false for already noted. */
-/* NB that this is called also from fields.c where *aw is a temporary
- * but pend is from pkg_db_find()! */
+/*
+ * Note: This is called also from fields.c where *aw is a temporary
+ * but pend is from pkg_db_find()!
+ *
+ * @retval true  For done.
+ * @retval false For already noted.
+ */
 bool
 trig_note_aw(struct pkginfo *pend, struct pkginfo *aw)
 {
@@ -219,7 +235,7 @@ trig_enqueue_awaited_pend(struct pkginfo *pend)
  * while in modstatdb_note, and the package in triggers-pending had its
  * state modified but dpkg could not finish clearing the awaiters.
  *
- * XXX: possibly get rid of some of the checks done somewhere else for
+ * XXX: Possibly get rid of some of the checks done somewhere else for
  *      this condition at run-time.
  */
 void
@@ -238,7 +254,7 @@ trig_fixup_awaiters(enum modstatdb_rw cstatus)
 	trig_awaited_pend_head = NULL;
 }
 
-/*---------- generalised handling of trigger kinds ----------*/
+/*---------- Generalized handling of trigger kinds. ----------*/
 
 struct trigkindinfo {
 	/* Only for trig_activate_start. */
@@ -279,7 +295,8 @@ invalid:
 	return &tki_unknown;
 }
 
-/* Calling sequence is:
+/*
+ * Calling sequence is:
  *  trig_activate_start(triggername)
  *  dtki->activate_awaiter(awaiting_package) } zero or more times
  *  dtki->activate_awaiter(0)                }  in any order
@@ -293,7 +310,7 @@ trig_activate_start(const char *name)
 	dtki->activate_start();
 }
 
-/*---------- unknown trigger kinds ----------*/
+/*---------- Unknown trigger kinds. ----------*/
 
 static void
 trk_unknown_activate_start(void)
@@ -325,7 +342,7 @@ static const struct trigkindinfo tki_unknown = {
 	.interest_change = trk_unknown_interest_change,
 };
 
-/*---------- explicit triggers ----------*/
+/*---------- Explicit triggers. ----------*/
 
 static FILE *trk_explicit_f;
 static struct varbuf trk_explicit_fn;
@@ -450,7 +467,7 @@ static const struct trigkindinfo tki_explicit = {
 	.interest_change = trk_explicit_interest_change,
 };
 
-/*---------- file triggers ----------*/
+/*---------- File triggers. ----------*/
 
 static struct {
 	struct trigfileint *head, *tail;
@@ -458,14 +475,15 @@ static struct {
 
 /*
  * Values:
- *  -1: not read,
- *   0: not edited
- *   1: edited
+ *  -1: Not read.
+ *   0: Not edited.
+ *   1: Edited
  */
 static int filetriggers_edited = -1;
 
-/* Called by various people with signum -1 and +1 to mean remove and add
- * and also by trig_file_interests_ensure with signum +2 meaning add
+/*
+ * Called by various people with signum -1 and +1 to mean remove and add
+ * and also by trig_file_interests_ensure() with signum +2 meaning add
  * but die if already present.
  */
 static void
@@ -486,7 +504,7 @@ trk_file_interest_change(const char *trig, struct pkginfo *pkg, int signum)
 		if (tfi->pkg == pkg)
 			goto found;
 
-	/* not found */
+	/* Not found. */
 	if (signum < 0)
 		return;
 
@@ -506,7 +524,7 @@ found:
 	if (signum > 0)
 		return;
 
-	/* remove it: */
+	/* Remove it: */
 	*search = tfi->samefile_next;
 	LIST_UNLINK_PART(filetriggers, tfi, inoverall.);
 edited:
@@ -642,7 +660,7 @@ static const struct trigkindinfo tki_file = {
 	.interest_change = trk_file_interest_change,
 };
 
-/*---------- trigger control info file ----------*/
+/*---------- Trigger control info file. ----------*/
 
 static void
 trig_cicb_interest_change(const char *trig, struct pkginfo *pkg, int signum)
@@ -701,8 +719,7 @@ trig_parse_ci(const char *file, trig_parse_cicb *interest,
 	f = fopen(file, "r");
 	if (!f) {
 		if (errno == ENOENT)
-			/* No file is just like an empty one. */
-			return;
+			return; /* No file is just like an empty one. */
 		ohshite(_("unable to open triggers ci file `%.250s'"), file);
 	}
 	push_cleanup(cu_closefile, ~0, NULL, 0, 1, f);
@@ -731,10 +748,10 @@ trig_parse_ci(const char *file, trig_parse_cicb *interest,
 			       cmd);
 		}
 	}
-	pop_cleanup(ehflag_normaltidy); /* fclose */
+	pop_cleanup(ehflag_normaltidy); /* fclose() */
 }
 
-/*---------- Unincorp file incorporation ----------*/
+/*---------- Unincorp file incorporation. ----------*/
 
 static void
 tdm_incorp_trig_begin(const char *trig)
@@ -822,7 +839,7 @@ trig_incorporate(enum modstatdb_rw cstatus, const char *admindir)
 	trigdef_process_done();
 }
 
-/*---------- default hooks ----------*/
+/*---------- Default hooks. ----------*/
 
 struct filenamenode {
 	struct filenamenode *next;

lib/dpkg/utils.c

@@ -25,10 +25,13 @@
 #include <dpkg/i18n.h>
 #include <dpkg/dpkg.h>
 
-/* Reimplementation of the standard ctype.h is* functions. Since gettext
+/*
+ * Reimplementation of the standard ctype.h is* functions. Since gettext
  * has overloaded the meaning of LC_CTYPE we can't use that to force C
  * locale, so use these cis* functions instead.
  */
+
+
 int cisdigit(int c) {
 	return (c>='0') && (c<='9');
 }

lib/dpkg/varbuf.h

@@ -34,7 +34,7 @@ DPKG_BEGIN_DECLS
  * (including before any call to varbuf_destroy), or the variable must be
  * initialized with VARBUF_INIT.
  *
- * However, varbufs allocated ‘static’ are properly initialised anyway and
+ * However, varbufs allocated ‘static’ are properly initialized anyway and
  * do not need varbufinit; multiple consecutive calls to varbufinit before
  * any use are allowed.
  *

lib/dpkg/vercmp.c

@@ -35,7 +35,9 @@ epochsdiffer(const struct versionrevision *a,
   return a->epoch != b->epoch;
 }
 
-/* assume ascii; warning: evaluates x multiple times! */
+/*
+ * Assume ASCII; Warning: evaluates x multiple times!
+ */
 #define order(x) ((x) == '~' ? -1 \
 		: cisdigit((x)) ? 0 \
 		: !(x) ? 0 \

m4/dpkg-compiler.m4

@@ -52,23 +52,23 @@ AC_DEFUN([DPKG_TRY_C99],
 #include <stdbool.h>
 #include <stdio.h>
 
-/* Variadic macro arguments */
+/* Variadic macro arguments. */
 #define variadic_macro(foo, ...) printf(foo, __VA_ARGS__)
 ]],
 [[
-	/* Compound initialisers */
+	/* Compound initializers. */
 	struct { int a, b; } foo = { .a = 1, .b = 2 };
 
-	/* Trailing comma in enum */
+	/* Trailing comma in enum. */
 	enum { first, second, } quux;
 
-	/* Boolean type */
+	/* Boolean type. */
 	bool bar = false;
 
-	/* Specific size type */
+	/* Specific size type. */
 	uint32_t baz = 0;
 
-	/* Magic __func__ variable */
+	/* Magic __func__ variable. */
 	printf("%s", __func__);
 ]])], [$1], [$2])dnl
 ])# DPKG_TRY_C99

scripts/Dpkg/Shlibs/Symbol.pm

@@ -312,7 +312,7 @@ sub get_pattern {
 
 ### NOTE: subroutines below require (or initialize) $self to be a pattern ###
 
-# Initialises this symbol as a pattern of the specified type.
+# Initializes this symbol as a pattern of the specified type.
 sub init_pattern {
     my ($self, $type) = @_;
 

src/archives.c

@@ -66,7 +66,9 @@
 struct pkginfo *conflictor[MAXCONFLICTORS];
 int cflict_index = 0;
 
-/* special routine to handle partial reads from the tarfile */
+/**
+ * Special routine to handle partial reads from the tarfile.
+ */
 static int safe_read(int fd, void *buf, int len)
 {
   int r, have= 0;
@@ -87,7 +89,9 @@ static int safe_read(int fd, void *buf, int len)
 static struct obstack tar_obs;
 static bool tarobs_init = false;
 
-/* ensure the obstack is properly initialized */
+/**
+ * Ensure the obstack is properly initialized.
+ */
 static void ensureobstackinit(void) {
 
   if (!tarobs_init) {
@@ -96,7 +100,9 @@ static void ensureobstackinit(void) {
   }
 }
 
-/* destroy the obstack */
+/**
+ * Destroy the obstack.
+ */
 static void destroyobstack(void) {
   if (tarobs_init) {
     obstack_free(&tar_obs, NULL);
@@ -104,6 +110,14 @@ static void destroyobstack(void) {
   }
 }
 
+/**
+ * Check if a file or directory will save a package from disappearance.
+ *
+ * A package can only be saved by a file or directory which is part
+ * only of itself - it must be neither part of the new package being
+ * installed nor part of any 3rd package (this is important so that
+ * shared directories don't stop packages from disappearing).
+ */
 bool
 filesavespackage(struct fileinlist *file,
                  struct pkginfo *pkgtobesaved,
@@ -114,16 +128,11 @@ filesavespackage(struct fileinlist *file,
   
   debug(dbg_eachfiledetail,"filesavespackage file `%s' package %s",
         file->namenode->name,pkgtobesaved->name);
-  /* A package can only be saved by a file or directory which is part
-   * only of itself - it must be neither part of the new package being
-   * installed nor part of any 3rd package (this is important so that
-   * shared directories don't stop packages from disappearing).
-   */
+
   /* If the file is a contended one and it's overridden by either
    * the package we're considering disappearing or the package
    * we're installing then they're not actually the same file, so
-   * we can't disappear the package - it is saved by this file.
-   */
+   * we can't disappear the package - it is saved by this file. */
   if (file->namenode->divert && file->namenode->divert->useinstead) {
     divpkg= file->namenode->divert->pkg;
     if (divpkg == pkgtobesaved || divpkg == pkgbeinginstalled) {
@@ -131,15 +140,13 @@ filesavespackage(struct fileinlist *file,
       return true;
     }
   }
-  /* Is the file in the package being installed ?  If so then it can't save.
-   */
+  /* Is the file in the package being installed? If so then it can't save. */
   if (file->namenode->flags & fnnf_new_inarchive) {
     debug(dbg_eachfiledetail,"filesavespackage ... in new archive -- no save");
     return false;
   }
   /* Look for a 3rd package which can take over the file (in case
-   * it's a directory which is shared by many packages.
-   */
+   * it's a directory which is shared by many packages. */
   iter = filepackages_iter_new(file->namenode);
   while ((thirdpkg = filepackages_iter_next(iter))) {
     debug(dbg_eachfiledetail, "filesavespackage ... also in %s",
@@ -188,8 +195,7 @@ tarfile_skip_one_forward(struct tarcontext *tc, struct tar_entry *ti)
   char databuf[TARBLKSZ];
 
   /* We need to advance the tar file to the next object, so read the
-   * file data and set it to oblivion.
-   */
+   * file data and set it to oblivion. */
   if (ti->type == tar_filetype_file) {
     char fnamebuf[256];
 
@@ -310,10 +316,18 @@ void setupfnamevbs(const char *filename) {
         fnamevb.buf, fnametmpvb.buf, fnamenewvb.buf);
 }
 
+/**
+ * Securely remove a pathname.
+ *
+ * This is a secure version of remove(3) using secure_unlink() instead of
+ * unlink(2).
+ *
+ * @retval  0 On success.
+ * @retval -1 On failure, just like unlink(2) & rmdir(2).
+ */
 int
 secure_remove(const char *filename)
 {
-  /* Returns 0 on success or -1 on failure, just like unlink & rmdir */
   int r, e;
   
   if (!rmdir(filename)) {
@@ -375,7 +389,7 @@ linktosameexistingdir(const struct tar_entry *ti, const char *fname,
   if (!S_ISDIR(oldstab.st_mode))
     return false;
 
-  /* But is it to the same dir ? */
+  /* But is it to the same dir? */
   varbufreset(symlinkfn);
   if (ti->linkname[0] == '/') {
     varbufaddstr(symlinkfn, instdir);
@@ -425,9 +439,8 @@ tarobject(void *ctx, struct tar_entry *ti)
   ensureobstackinit();
 
   /* Append to list of files.
-   * The trailing / put on the end of names in tarfiles has already
-   * been stripped by tar_extractor (lib/tarfn.c).
-   */
+   * The trailing ‘/’ put on the end of names in tarfiles has already
+   * been stripped by tar_extractor(). */
   oldnifd= tc->newfilesp;
   nifd= addfiletolist(tc, findnamenode(ti->name, 0));
   nifd->namenode->flags |= fnnf_new_inarchive;
@@ -473,8 +486,7 @@ tarobject(void *ctx, struct tar_entry *ti)
 
   if (nifd->namenode->flags & fnnf_new_conff) {
     /* If it's a conffile we have to extract it next to the installed
-     * version (ie, we do the usual link-following).
-     */
+     * version (i.e. we do the usual link-following). */
     if (conffderef(tc->pkg, &conffderefn, usename))
       usename= conffderefn.buf;
     debug(dbg_conff,"tarobject fnnf_new_conff deref=`%s'",usename);
@@ -491,8 +503,7 @@ tarobject(void *ctx, struct tar_entry *ti)
     /* OK, so it doesn't exist.
      * However, it's possible that we were in the middle of some other
      * backup/restore operation and were rudely interrupted.
-     * So, we see if we have .dpkg-tmp, and if so we restore it.
-     */
+     * So, we see if we have .dpkg-tmp, and if so we restore it. */
     if (rename(fnametmpvb.buf,fnamevb.buf)) {
       if (errno != ENOENT && errno != ENOTDIR)
         ohshite(_("unable to clean up mess surrounding `%.255s' before "
@@ -509,9 +520,8 @@ tarobject(void *ctx, struct tar_entry *ti)
   }
 
   /* Check to see if it's a directory or link to one and we don't need to
-   * do anything.  This has to be done now so that we don't die due to
-   * a file overwriting conflict.
-   */
+   * do anything. This has to be done now so that we don't die due to
+   * a file overwriting conflict. */
   existingdirectory = false;
   switch (ti->type) {
   case tar_filetype_symlink:
@@ -563,7 +573,7 @@ tarobject(void *ctx, struct tar_entry *ti)
           continue;
       }
 
-      /* Nope ?  Hmm, file conflict, perhaps.  Check Replaces. */
+      /* Nope? Hmm, file conflict, perhaps. Check Replaces. */
       switch (otherpkg->clientdata->replacingfilesandsaid) {
       case 2:
         keepexisting = true;
@@ -599,7 +609,7 @@ tarobject(void *ctx, struct tar_entry *ti)
         }
         if (conff) {
           debug(dbg_eachfiledetail, "tarobject other's obsolete conffile");
-          /* processarc.c will have copied its hash already. */
+          /* process_archive() will have copied its hash already. */
           continue;
         }
       }
@@ -624,9 +634,9 @@ tarobject(void *ctx, struct tar_entry *ti)
                       versiondescribe(&otherpkg->installed.version,
                                       vdew_nonambig));
         } else {
-          /* WTA: At this point we are replacing something without a Replaces.
-           * if the new object is a directory and the previous object does not
-           * exist assume it's also a directory and don't complain. */
+          /* At this point we are replacing something without a Replaces.
+           * If the new object is a directory and the previous object does
+           * not exist assume it's also a directory and don't complain. */
           if (!(statr && ti->type == tar_filetype_dir))
             forcibleerr(fc_overwrite,
                         _("trying to overwrite '%.250s', "
@@ -657,19 +667,18 @@ tarobject(void *ctx, struct tar_entry *ti)
   if (existingdirectory)
     return 0;
 
-  /* Now, at this stage we want to make sure neither of .dpkg-new and .dpkg-tmp
-   * are hanging around.
-   */
+  /* Now, at this stage we want to make sure neither of .dpkg-new and
+   * .dpkg-tmp are hanging around. */
   ensure_pathname_nonexisting(fnamenewvb.buf);
   ensure_pathname_nonexisting(fnametmpvb.buf);
 
   /* Now we start to do things that we need to be able to undo
-   * if something goes wrong.  Watch out for the CLEANUP comments to
-   * keep an eye on what's installed on the disk at each point.
-   */
+   * if something goes wrong. Watch out for the CLEANUP comments to
+   * keep an eye on what's installed on the disk at each point. */
   push_cleanup(cu_installnew, ~ehflag_normaltidy, NULL, 0, 1, (void *)nifd);
 
-  /* CLEANUP: Now we either have the old file on the disk, or not, in
+  /*
+   * CLEANUP: Now we either have the old file on the disk, or not, in
    * its original filename.
    */
 
@@ -677,8 +686,7 @@ tarobject(void *ctx, struct tar_entry *ti)
   switch (ti->type) {
   case tar_filetype_file:
     /* We create the file with mode 0 to make sure nobody can do anything with
-     * it until we apply the proper mode, which might be a statoverride.
-     */
+     * it until we apply the proper mode, which might be a statoverride. */
     fd= open(fnamenewvb.buf, (O_CREAT|O_EXCL|O_WRONLY), 0);
     if (fd < 0)
       ohshite(_("unable to create `%.255s' (while processing `%.255s')"),
@@ -708,7 +716,7 @@ tarobject(void *ctx, struct tar_entry *ti)
     /* Postpone the fsync, to try to avoid massive I/O degradation. */
     nifd->namenode->flags |= fnnf_deferred_fsync;
 
-    pop_cleanup(ehflag_normaltidy); /* fd= open(fnamenewvb.buf) */
+    pop_cleanup(ehflag_normaltidy); /* fd = open(fnamenewvb.buf) */
     if (close(fd))
       ohshite(_("error closing/writing `%.255s'"), ti->name);
     newtarobject_utime(fnamenewvb.buf, st);
@@ -765,17 +773,17 @@ tarobject(void *ctx, struct tar_entry *ti)
 
   set_selinux_path_context(fnamevb.buf, fnamenewvb.buf, st->mode);
 
-  /* CLEANUP: Now we have extracted the new object in .dpkg-new (or,
-   * if the file already exists as a directory and we were trying to extract
-   * a directory or symlink, we returned earlier, so we don't need
-   * to worry about that here).
+  /*
+   * CLEANUP: Now we have extracted the new object in .dpkg-new (or,
+   * if the file already exists as a directory and we were trying to
+   * extract a directory or symlink, we returned earlier, so we don't
+   * need to worry about that here).
    *
    * The old file is still in the original filename,
    */
 
-  /* First, check to see if it's a conffile.  If so we don't install
-   * it now - we leave it in .dpkg-new for --configure to take care of
-   */
+  /* First, check to see if it's a conffile. If so we don't install
+   * it now - we leave it in .dpkg-new for --configure to take care of. */
   if (nifd->namenode->flags & fnnf_new_conff) {
     debug(dbg_conffdetail,"tarobject conffile extracted");
     nifd->namenode->flags |= fnnf_elide_other_lists;
@@ -783,9 +791,9 @@ tarobject(void *ctx, struct tar_entry *ti)
   }
 
   /* Now we move the old file out of the way, the backup file will
-   * be deleted later.
-   */
-  if (statr) { /* Don't try to back it up if it didn't exist. */
+   * be deleted later. */
+  if (statr) {
+    /* Don't try to back it up if it didn't exist. */
     debug(dbg_eachfiledetail,"tarobject new - no backup");
   } else {
     if (ti->type == tar_filetype_dir || S_ISDIR(stab.st_mode)) {
@@ -796,9 +804,9 @@ tarobject(void *ctx, struct tar_entry *ti)
         ohshite(_("unable to move aside `%.255s' to install new version"),
                 ti->name);
     } else if (S_ISLNK(stab.st_mode)) {
-      /* We can't make a symlink with two hardlinks, so we'll have to copy it.
-       * (Pretend that making a copy of a symlink is the same as linking to it.)
-       */
+      /* We can't make a symlink with two hardlinks, so we'll have to
+       * copy it. (Pretend that making a copy of a symlink is the same
+       * as linking to it.) */
       varbufreset(&symlinkfn);
       varbuf_grow(&symlinkfn, stab.st_size + 1);
       r = readlink(fnamevb.buf, symlinkfn.buf, symlinkfn.size);
@@ -820,8 +828,9 @@ tarobject(void *ctx, struct tar_entry *ti)
     }
   }
 
-  /* CLEANUP: now the old file is in dpkg-tmp, and the new file is still
-   * in dpkg-new.
+  /*
+   * CLEANUP: Now the old file is in .dpkg-tmp, and the new file is still
+   * in .dpkg-new.
    */
 
   if (ti->type == tar_filetype_file) {
@@ -832,10 +841,12 @@ tarobject(void *ctx, struct tar_entry *ti)
     if (rename(fnamenewvb.buf, fnamevb.buf))
       ohshite(_("unable to install new version of `%.255s'"), ti->name);
 
-    /* CLEANUP: now the new file is in the destination file, and the
-     * old file is in dpkg-tmp to be cleaned up later.  We now need
+    /*
+     * CLEANUP: Now the new file is in the destination file, and the
+     * old file is in .dpkg-tmp to be cleaned up later. We now need
      * to take a different attitude to cleanup, because we need to
-     * remove the new file. */
+     * remove the new file.
+     */
 
     nifd->namenode->flags |= fnnf_placed_on_disk;
     nifd->namenode->flags |= fnnf_elide_other_lists;
@@ -895,10 +906,12 @@ tar_deferred_extract(struct fileinlist *files, struct pkginfo *pkg)
 
     cfile->namenode->flags &= ~fnnf_deferred_rename;
 
-    /* CLEANUP: now the new file is in the destination file, and the
-     * old file is in dpkg-tmp to be cleaned up later.  We now need
+    /*
+     * CLEANUP: Now the new file is in the destination file, and the
+     * old file is in .dpkg-tmp to be cleaned up later. We now need
      * to take a different attitude to cleanup, because we need to
-     * remove the new file. */
+     * remove the new file.
+     */
 
     cfile->namenode->flags |= fnnf_placed_on_disk;
     cfile->namenode->flags |= fnnf_elide_other_lists;
@@ -907,23 +920,27 @@ tar_deferred_extract(struct fileinlist *files, struct pkginfo *pkg)
   }
 }
 
+/**
+ * Try if we can deconfigure the package and queue it if so.
+ *
+ * Also checks whether the pdep is forced, first, according to force_p.
+ * force_p may be NULL in which case nothing is considered forced.
+ *
+ * Action is a string describing the action which causes the
+ * deconfiguration:
+ *
+ *   "removal of <package>"       (due to Conflicts+Depends; removal != NULL)
+ *   "installation of <package>"  (due to Breaks;            removal == NULL)
+ *
+ * @retval 0 Not possible (why is printed).
+ * @retval 1 Deconfiguration queued ok (no message printed).
+ * @retval 2 Forced (no deconfiguration needed, why is printed).
+ */
 static int
 try_deconfigure_can(bool (*force_p)(struct deppossi *), struct pkginfo *pkg,
                     struct deppossi *pdep, const char *action,
                     struct pkginfo *removal, const char *why)
 {
-  /* Also checks whether the pdep is forced, first, according to force_p.
-   * force_p may be 0 in which case nothing is considered forced.
-   *
-   * Action is a string describing the action which causes the
-   * deconfiguration:
-   *     removal of <package>         (due to Conflicts+Depends   removal!=0)
-   *     installation of <package>    (due to Breaks              removal==0)
-   *
-   * Return values:  2: forced (no deconfiguration needed, why is printed)
-   *                 1: deconfiguration queued ok (no message printed)
-   *                 0: not possible (why is printed)
-   */
   struct pkg_deconf_list *newdeconf;
   
   if (force_p && force_p(pdep)) {
@@ -1113,7 +1130,8 @@ void check_conflict(struct dependency *dep, struct pkginfo *pkg,
                 fixbyrm->name, pkg->name);
         return;
       }
-      fixbyrm->clientdata->istobe= itb_normal; /* put it back */
+      /* Put it back. */
+      fixbyrm->clientdata->istobe = itb_normal;
     }
   }
   varbufaddc(&conflictwhy,0);
@@ -1281,21 +1299,23 @@ void archivefiles(const char *const *argv) {
   modstatdb_shutdown();
 }
 
+/**
+ * Decide whether we want to install a new version of the package.
+ *
+ * ver is the version we might want to install. If saywhy is 1 then
+ * if we skip the package we say what we are doing (and, if we are
+ * selecting a previously deselected package, say so and actually do
+ * the select). want_install returns 0 if the package should be
+ * skipped and 1 if it should be installed.
+ *
+ * ver may be 0, in which case saywhy must be 0 and want_install may
+ * also return -1 to mean it doesn't know because it would depend on
+ * the version number.
+ */
 int
 wanttoinstall(struct pkginfo *pkg, const struct versionrevision *ver,
               bool saywhy)
 {
-  /* Decide whether we want to install a new version of the package.
-   * ver is the version we might want to install.  If saywhy is 1 then
-   * if we skip the package we say what we are doing (and, if we are
-   * selecting a previously deselected package, say so and actually do
-   * the select).  want_install returns 0 if the package should be
-   * skipped and 1 if it should be installed.
-   *
-   * ver may be 0, in which case saywhy must be 0 and want_install may
-   * also return -1 to mean it doesn't know because it would depend on
-   * the version number.
-   */
   int r;
 
   if (pkg->want != want_install && pkg->want != want_hold) {

src/cleanup.c

@@ -46,21 +46,25 @@
 
 int cleanup_pkg_failed=0, cleanup_conflictor_failed=0;
 
+/**
+ * Something went wrong and we're undoing.
+ *
+ * We have the following possible situations for non-conffiles:
+ *   <foo>.dpkg-tmp exists - in this case we want to remove
+ *    <foo> if it exists and replace it with <foo>.dpkg-tmp.
+ *    This undoes the backup operation.
+ *   <foo>.dpkg-tmp does not exist - <foo> may be on the disk,
+ *    as a new file which didn't fail, remove it if it is.
+ *
+ * In both cases, we also make sure we delete <foo>.dpkg-new in
+ * case that's still hanging around.
+ *
+ * For conffiles, we simply delete <foo>.dpkg-new. For these,
+ * <foo>.dpkg-tmp shouldn't exist, as we don't make a backup
+ * at this stage. Just to be on the safe side, though, we don't
+ * look for it.
+ */
 void cu_installnew(int argc, void **argv) {
-  /* Something went wrong and we're undoing.
-   * We have the following possible situations for non-conffiles:
-   *   <foo>.dpkg-tmp exists - in this case we want to remove
-   *    <foo> if it exists and replace it with <foo>.dpkg-tmp.
-   *    This undoes the backup operation.
-   *   <foo>.dpkg-tmp does not exist - <foo> may be on the disk,
-   *    as a new file which didn't fail, remove it if it is.
-   * In both cases, we also make sure we delete <foo>.dpkg-new in
-   * case that's still hanging around.
-   * For conffiles, we simply delete <foo>.dpkg-new.  For these,
-   * <foo>.dpkg-tmp shouldn't exist, as we don't make a backup
-   * at this stage.  Just to be on the safe side, though, we don't
-   * look for it.
-   */
   struct fileinlist *nifd= (struct fileinlist*)argv[0];
   struct filenamenode *namenode;
   struct stat stab;
@@ -73,13 +77,11 @@ void cu_installnew(int argc, void **argv) {
   setupfnamevbs(namenode->name);
   
   if (!(namenode->flags & fnnf_new_conff) && !lstat(fnametmpvb.buf,&stab)) {
-    /* OK, <foo>.dpkg-tmp exists.  Remove <foo> and
-     * restore <foo>.dpkg-tmp ...
-     */
+    /* OK, <foo>.dpkg-tmp exists. Remove <foo> and
+     * restore <foo>.dpkg-tmp ... */
     if (namenode->flags & fnnf_no_atomic_overwrite) {
       /* If we can't do an atomic overwrite we have to delete first any
-       * link to the new version we may have created.
-       */
+       * link to the new version we may have created. */
       debug(dbg_eachfiledetail,"cu_installnew restoring nonatomic");
       if (secure_remove(fnamevb.buf) && errno != ENOENT && errno != ENOTDIR)
         ohshite(_("unable to remove newly-installed version of `%.250s' to allow"
@@ -122,18 +124,23 @@ void cu_prermupgrade(int argc, void **argv) {
   cleanup_pkg_failed--;
 }
 
+/*
+ * Also has conflictor in argv[1] and infavour in argv[2].
+ * conflictor may be NULL if deconfigure was due to Breaks.
+ */
 void ok_prermdeconfigure(int argc, void **argv) {
   struct pkginfo *deconf= (struct pkginfo*)argv[0];
-  /* also has conflictor in argv[1] and infavour in argv[2].
-   * conflictor may be 0 if deconfigure was due to Breaks */
   
   if (cipaction->arg == act_install)
     add_to_queue(deconf);
 }
 
+/*
+ * conflictor may be NULL.
+ */
 void cu_prermdeconfigure(int argc, void **argv) {
   struct pkginfo *deconf= (struct pkginfo*)argv[0];
-  struct pkginfo *conflictor= (struct pkginfo*)argv[1]; /* may be 0 */
+  struct pkginfo *conflictor = (struct pkginfo *)argv[1];
   struct pkginfo *infavour= (struct pkginfo*)argv[2];
 
   if (conflictor) {

src/configure.c

@@ -275,11 +275,13 @@ deferred_configure(struct pkginfo *pkg)
 
 	trigproc_reset_cycle();
 
-	/* At this point removal from the queue is confirmed. This
+	/*
+	 * At this point removal from the queue is confirmed. This
 	 * represents irreversible progress wrt trigger cycles. Only
 	 * packages in stat_unpacked are automatically added to the
 	 * configuration queue, and during configuration and trigger
-	 * processing new packages can't enter into unpacked. */
+	 * processing new packages can't enter into unpacked.
+	 */
 
 	ok = breakses_ok(pkg, &aemsgs) ? ok : 0;
 	if (ok == 0) {
@@ -501,7 +503,7 @@ showdiff(const char *old, const char *new)
 		/* Child process. */
 		const char *pager;
 		const char *shell;
-		char cmdbuf[1024];	/* command to run */
+		char cmdbuf[1024];
 
 		pager = getenv(PAGERENV);
 		if (!pager || !*pager)

src/depcon.c

@@ -53,11 +53,10 @@ foundcyclebroken(struct cyclesofarlink *thislink, struct cyclesofarlink *sofar,
 
   if(!possi)
     return false;
-  /* We're investigating the dependency `possi' to see if it
-   * is part of a loop.  To this end we look to see whether the
+  /* We're investigating the dependency ‘possi’ to see if it
+   * is part of a loop. To this end we look to see whether the
    * depended-on package is already one of the packages whose
-   * dependencies we're searching.
-   */
+   * dependencies we're searching. */
   for (sol = sofar; sol && sol->pkg != dependedon; sol = sol->prev);
 
   /* If not, we do a recursive search on it to see what we find. */
@@ -65,15 +64,14 @@ foundcyclebroken(struct cyclesofarlink *thislink, struct cyclesofarlink *sofar,
     return findbreakcyclerecursive(dependedon, thislink);
   
   debug(dbg_depcon,"found cycle");
-  /* Right, we now break one of the links.  We prefer to break
+  /* Right, we now break one of the links. We prefer to break
    * a dependency of a package without a postinst script, as
-   * this is a null operation.  If this is not possible we break
+   * this is a null operation. If this is not possible we break
    * the other link in the recursive calling tree which mentions
    * this package (this being the first package involved in the
-   * cycle).  It doesn't particularly matter which we pick, but if
+   * cycle). It doesn't particularly matter which we pick, but if
    * we break the earliest dependency we came across we may be
-   * able to do something straight away when findbreakcycle returns.
-   */
+   * able to do something straight away when findbreakcycle returns. */
   sofar= thislink;
   for (sol = sofar; !(sol != sofar && sol->pkg == dependedon); sol = sol->prev) {
     postinstfilename= pkgadminfile(sol->pkg,POSTINSTFILE);
@@ -83,22 +81,22 @@ foundcyclebroken(struct cyclesofarlink *thislink, struct cyclesofarlink *sofar,
     }
   }
   /* Now we have either a package with no postinst, or the other
-   * occurrence of the current package in the list.
-   */
+   * occurrence of the current package in the list. */
   sol->possi->cyclebreak = true;
   debug(dbg_depcon, "cycle broken at %s -> %s",
         sol->possi->up->up->name, sol->possi->ed->name);
   return true;
 }
 
+/**
+ * Cycle breaking works recursively down the package dependency tree.
+ *
+ * ‘sofar’ is the list of packages we've descended down already - if we
+ * encounter any of its packages again in a dependency we have found a cycle.
+ */
 static bool
 findbreakcyclerecursive(struct pkginfo *pkg, struct cyclesofarlink *sofar)
 {
-  /* Cycle breaking works recursively down the package dependency
-   * tree.  `sofar' is the list of packages we've descended down
-   * already - if we encounter any of its packages again in a
-   * dependency we have found a cycle.
-   */
   struct cyclesofarlink thislink, *sol;
   struct dependency *dep;
   struct deppossi *possi, *providelink;
@@ -138,9 +136,8 @@ findbreakcyclerecursive(struct pkginfo *pkg, struct cyclesofarlink *sofar)
         if (providelink->up->type != dep_provides) continue;
         provider= providelink->up->up;
         if (provider->clientdata->istobe == itb_normal) continue;
-        /* We don't break things at `provides' links, so `possi' is
-         * still the one we use.
-         */
+        /* We don't break things at ‘provides’ links, so ‘possi’ is
+         * still the one we use. */
         if (foundcyclebroken(&thislink, sofar, provider, possi))
           return true;
       }
@@ -204,24 +201,28 @@ void describedepcon(struct varbuf *addto, struct dependency *dep) {
   varbuf_destroy(&depstr);
 }
   
+/*
+ * *whynot must already have been initialized; it need not be
+ * empty though - it will be reset before use.
+ *
+ * If depisok returns false for ‘not OK’ it will contain a description,
+ * newline-terminated BUT NOT NUL-TERMINATED, of the reason.
+ *
+ * If depisok returns true it will contain garbage.
+ * allowunconfigd should be non-zero during the ‘Pre-Depends’ checking
+ * before a package is unpacked, when it is sufficient for the package
+ * to be unpacked provided that both the unpacked and previously-configured
+ * versions are acceptable.
+ *
+ * On false return (‘not OK’), *canfixbyremove refers to a package which
+ * if removed (dep_conflicts) or deconfigured (dep_breaks) will fix
+ * the problem. Caller may pass NULL for canfixbyremove and need not
+ * initialize *canfixbyremove.
+ */
 bool
 depisok(struct dependency *dep, struct varbuf *whynot,
         struct pkginfo **canfixbyremove, bool allowunconfigd)
 {
-  /* *whynot must already have been initialised; it need not be
-   * empty though - it will be reset before use.
-   * If depisok returns false for ‘not OK’ it will contain a description,
-   * newline-terminated BUT NOT NULL-TERMINATED, of the reason.
-   * If depisok returns true it will contain garbage.
-   * allowunconfigd should be true during the ‘Pre-Depends’ checking
-   * before a package is unpacked, when it is sufficient for the package
-   * to be unpacked provided that both the unpacked and previously-configured
-   * versions are acceptable.
-   * On false return (‘not OK’), *canfixbyremove refers to a package which
-   * if removed (dep_conflicts) or deconfigured (dep_breaks) will fix
-   * the problem.  Caller may pass 0 for canfixbyremove and need not
-   * initialise *canfixbyremove.
-   */
   struct deppossi *possi;
   struct deppossi *provider;
   int nconflicts;
@@ -229,8 +230,7 @@ depisok(struct dependency *dep, struct varbuf *whynot,
   /* Use this buffer so that when internationalisation comes along we
    * don't have to rewrite the code completely, only redo the sprintf strings
    * (assuming we have the fancy argument-number-specifiers).
-   * Allow 250x3 for package names, versions, &c, + 250 for ourselves.
-   */
+   * Allow 250x3 for package names, versions, &c, + 250 for ourselves. */
   char linebuf[1024];
 
   assert(dep->type == dep_depends || dep->type == dep_predepends ||
@@ -242,13 +242,12 @@ depisok(struct dependency *dep, struct varbuf *whynot,
     *canfixbyremove = NULL;
 
   /* The dependency is always OK if we're trying to remove the depend*ing*
-   * package.
-   */
+   * package. */
   switch (dep->up->clientdata->istobe) {
   case itb_remove: case itb_deconfigure:
     return true;
   case itb_normal:
-    /* Only installed packages can be make dependency problems */
+    /* Only installed packages can be make dependency problems. */
     switch (dep->up->status) {
     case stat_installed:
     case stat_triggerspending:
@@ -273,15 +272,14 @@ depisok(struct dependency *dep, struct varbuf *whynot,
   describedepcon(whynot, dep);
   varbufaddc(whynot,'\n');
   
-  /* TODO: check dep_enhances as well (WTA) */
+  /* TODO: Check dep_enhances as well. */
   if (dep->type == dep_depends || dep->type == dep_predepends ||
       dep->type == dep_recommends || dep->type == dep_suggests ) {
     
-    /* Go through the alternatives.  As soon as we find one that
+    /* Go through the alternatives. As soon as we find one that
      * we like, we return ‘true’ straight away. Otherwise, when we get to
      * the end we'll have accumulated all the reasons in whynot and
-     * can return ‘false’.
-     */
+     * can return ‘false’. */
 
     for (possi= dep->list; possi; possi= possi->next) {
       switch (possi->ed->clientdata->istobe) {
@@ -311,8 +309,7 @@ depisok(struct dependency *dep, struct varbuf *whynot,
         case stat_notinstalled:
           /* Don't say anything about this yet - it might be a virtual package.
            * Later on, if nothing has put anything in linebuf, we know that it
-           * isn't and issue a diagnostic then.
-           */
+           * isn't and issue a diagnostic then. */
           *linebuf = '\0';
           break;
         case stat_unpacked:
@@ -372,9 +369,8 @@ depisok(struct dependency *dep, struct varbuf *whynot,
           case itb_installnew:
             /* Don't pay any attention to the Provides field of the
              * currently-installed version of the package we're trying
-             * to install.  We dealt with that by using the available
-             * information above.
-             */
+             * to install. We dealt with that by using the available
+             * information above. */
             continue; 
           case itb_remove:
             sprintf(linebuf, _("  %.250s provides %.250s but is to be removed.\n"),
@@ -400,8 +396,7 @@ depisok(struct dependency *dep, struct varbuf *whynot,
         
         if (!*linebuf) {
           /* If the package wasn't installed at all, and we haven't said
-           * yet why this isn't satisfied, we should say so now.
-           */
+           * yet why this isn't satisfied, we should say so now. */
           sprintf(linebuf, _("  %.250s is not installed.\n"), possi->ed->name);
           varbufaddstr(whynot, linebuf);
         }
@@ -412,21 +407,20 @@ depisok(struct dependency *dep, struct varbuf *whynot,
 
   } else {
     
-    /* It's conflicts or breaks.  There's only one main alternative,
+    /* It's conflicts or breaks. There's only one main alternative,
      * but we also have to consider Providers. We return ‘false’ as soon
      * as we find something that matches the conflict, and only describe
-     * it then. If we get to the end without finding anything we return ‘true’.
-     */
+     * it then. If we get to the end without finding anything we return
+     * ‘true’. */
 
     possi= dep->list;
     nconflicts= 0;
 
     if (possi->ed != possi->up->up) {
       /* If the package conflicts with or breaks itself it must mean
-       * other packages which provide the same virtual name.  We
+       * other packages which provide the same virtual name. We
        * therefore don't look at the real package and go on to the
-       * virtual ones.
-       */
+       * virtual ones. */
       
       switch (possi->ed->clientdata->istobe) {
       case itb_remove:
@@ -443,15 +437,17 @@ depisok(struct dependency *dep, struct varbuf *whynot,
         *canfixbyremove= possi->ed;
         break;
       case itb_deconfigure:
-        if (dep->type == dep_breaks) break; /* already deconfiguring this */
-        /* fall through */
+        if (dep->type == dep_breaks)
+          break; /* Already deconfiguring this. */
+        /* Fall through. */
       case itb_normal: case itb_preinstall:
         switch (possi->ed->status) {
         case stat_notinstalled: case stat_configfiles:
           break;
         case stat_halfinstalled: case stat_unpacked:
         case stat_halfconfigured:
-          if (dep->type == dep_breaks) break; /* no problem */
+          if (dep->type == dep_breaks)
+            break; /* No problem. */
         case stat_installed:
         case stat_triggerspending:
         case stat_triggersawaited:
@@ -482,7 +478,8 @@ depisok(struct dependency *dep, struct varbuf *whynot,
            provider = provider->rev_next) {
         if (provider->up->type != dep_provides) continue;
         if (provider->up->up->clientdata->istobe != itb_installnew) continue;
-        if (provider->up->up == dep->up) continue; /* conflicts and provides the same */
+        if (provider->up->up == dep->up)
+          continue; /* Conflicts and provides the same. */
         sprintf(linebuf, _("  %.250s provides %.250s and is to be installed.\n"),
                 provider->up->up->name, possi->ed->name);
         varbufaddstr(whynot, linebuf);
@@ -498,27 +495,29 @@ depisok(struct dependency *dep, struct varbuf *whynot,
            provider = provider->rev_next) {
         if (provider->up->type != dep_provides) continue;
           
-        if (provider->up->up == dep->up) continue; /* conflicts and provides the same */
+        if (provider->up->up == dep->up)
+          continue; /* Conflicts and provides the same. */
         
         switch (provider->up->up->clientdata->istobe) {
         case itb_installnew:
           /* Don't pay any attention to the Provides field of the
            * currently-installed version of the package we're trying
-           * to install.  We dealt with that package by using the
-           * available information above.
-           */
+           * to install. We dealt with that package by using the
+           * available information above. */
           continue; 
         case itb_remove:
           continue;
         case itb_deconfigure:
-          if (dep->type == dep_breaks) continue; /* already deconfiguring */
+          if (dep->type == dep_breaks)
+            continue; /* Already deconfiguring. */
         case itb_normal: case itb_preinstall:
           switch (provider->up->up->status) {
           case stat_notinstalled: case stat_configfiles:
             continue;
           case stat_halfinstalled: case stat_unpacked:
           case stat_halfconfigured:
-            if (dep->type == dep_breaks) break; /* no problem */
+            if (dep->type == dep_breaks)
+              break; /* No problem. */
           case stat_installed:
           case stat_triggerspending:
           case stat_triggersawaited:

src/enquiry.c

@@ -18,7 +18,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/* FIXME: per-package audit */
+/* FIXME: per-package audit. */
+
 #include <config.h>
 #include <compat.h>
 
@@ -322,17 +323,20 @@ void assertmulticonrep(const char *const *argv) {
   assert_version_support(argv, &version, _("multiple Conflicts and Replaces"));
 }
 
+/**
+ * Print a single package which:
+ *  (a) is the target of one or more relevant predependencies.
+ *  (b) has itself no unsatisfied pre-dependencies.
+ *
+ * If such a package is present output is the Packages file entry,
+ * which can be massaged as appropriate.
+ *
+ * Exit status:
+ *  0 = a package printed, OK
+ *  1 = no suitable package available
+ *  2 = error
+ */
 void predeppackage(const char *const *argv) {
-  /* Print a single package which:
-   *  (a) is the target of one or more relevant predependencies.
-   *  (b) has itself no unsatisfied pre-dependencies.
-   * If such a package is present output is the Packages file entry,
-   *  which can be massaged as appropriate.
-   * Exit status:
-   *  0 = a package printed, OK
-   *  1 = no suitable package available
-   *  2 = error
-   */
   static struct varbuf vb;
   
   struct pkgiterator *it;
@@ -344,36 +348,42 @@ void predeppackage(const char *const *argv) {
     badusage(_("--%s takes no arguments"), cipaction->olong);
 
   modstatdb_init(admindir,msdbrw_readonly);
-  clear_istobes(); /* We use clientdata->istobe to detect loops */
+  /* We use clientdata->istobe to detect loops. */
+  clear_istobes();
 
   dep = NULL;
   it = pkg_db_iter_new();
   while (!dep && (pkg = pkg_db_iter_next(it))) {
-    if (pkg->want != want_install) continue; /* Ignore packages user doesn't want */
-    if (!pkg->files) continue; /* Ignore packages not available */
+    /* Ignore packages user doesn't want. */
+    if (pkg->want != want_install)
+      continue;
+    /* Ignore packages not available. */
+    if (!pkg->files)
+      continue;
     pkg->clientdata->istobe= itb_preinstall;
     for (dep= pkg->available.depends; dep; dep= dep->next) {
       if (dep->type != dep_predepends) continue;
       if (depisok(dep, &vb, NULL, true))
         continue;
-      break; /* This will leave dep non-NULL, and so exit the loop. */
+      /* This will leave dep non-NULL, and so exit the loop. */
+      break;
     }
     pkg->clientdata->istobe= itb_normal;
     /* If dep is NULL we go and get the next package. */
   }
   pkg_db_iter_free(it);
 
-  if (!dep) exit(1); /* Not found */
+  if (!dep)
+    exit(1); /* Not found. */
   assert(pkg);
   startpkg= pkg;
   pkg->clientdata->istobe= itb_preinstall;
 
   /* OK, we have found an unsatisfied predependency.
    * Now go and find the first thing we need to install, as a first step
-   * towards satisfying it.
-   */
+   * towards satisfying it. */
   do {
-    /* We search for a package which would satisfy dep, and put it in pkg */
+    /* We search for a package which would satisfy dep, and put it in pkg. */
     for (possi = dep->list, pkg = NULL;
          !pkg && possi;
          possi=possi->next) {
@@ -405,11 +415,12 @@ void predeppackage(const char *const *argv) {
       if (dep->type != dep_predepends) continue;
       if (depisok(dep, &vb, NULL, true))
         continue;
-      break; /* This will leave dep non-NULL, and so exit the loop. */
+      /* This will leave dep non-NULL, and so exit the loop. */
+      break;
     }
   } while (dep);
 
-  /* OK, we've found it - pkg has no unsatisfied pre-dependencies ! */
+  /* OK, we've found it - pkg has no unsatisfied pre-dependencies! */
   writerecord(stdout, _("<standard output>"), pkg, &pkg->available);
 
   m_output(stdout, _("<standard output>"));
@@ -435,28 +446,32 @@ printinstarch(const char *const *argv)
 void cmpversions(const char *const *argv) {
   struct relationinfo {
     const char *string;
-    /* These values are exit status codes, so 0=true, 1=false */
+    /* These values are exit status codes, so 0 = true, 1 = false. */
     int if_lesser, if_equal, if_greater;
     int if_none_a, if_none_both, if_none_b;
   };
 
   static const struct relationinfo relationinfos[]= {
-   /*              < = > !a!2!b  */
+    /*             < = > !a!2!b  */
     { "le",        0,0,1, 0,0,1  },
     { "lt",        0,1,1, 0,1,1  },
     { "eq",        1,0,1, 1,0,1  },
     { "ne",        0,1,0, 0,1,0  },
     { "ge",        1,0,0, 1,0,0  },
     { "gt",        1,1,0, 1,1,0  },
-    { "le-nl",     0,0,1, 1,0,0  }, /* Here none        */
-    { "lt-nl",     0,1,1, 1,1,0  }, /* is counted       */
-    { "ge-nl",     1,0,0, 0,0,1  }, /* than any version.*/
-    { "gt-nl",     1,1,0, 0,1,1  }, /*                  */
-    { "<",         0,0,1, 0,0,1  }, /* For compatibility*/
-    { "<=",        0,0,1, 0,0,1  }, /* with dpkg        */
-    { "<<",        0,1,1, 0,1,1  }, /* control file     */
-    { "=",         1,0,1, 1,0,1  }, /* syntax           */
-    { ">",         1,0,0, 1,0,0  }, /*                  */
+
+    /* These treat an empty version as later than any version. */
+    { "le-nl",     0,0,1, 1,0,0  },
+    { "lt-nl",     0,1,1, 1,1,0  },
+    { "ge-nl",     1,0,0, 0,0,1  },
+    { "gt-nl",     1,1,0, 0,1,1  },
+
+    /* For compatibility with dpkg control file syntax. */
+    { "<",         0,0,1, 0,0,1  },
+    { "<=",        0,0,1, 0,0,1  },
+    { "<<",        0,1,1, 0,1,1  },
+    { "=",         1,0,1, 1,0,1  },
+    { ">",         1,0,0, 1,0,0  },
     { ">=",        1,0,0, 1,0,0  },
     { ">>",        1,1,0, 1,1,0  },
     { NULL                       }

src/filesdb.c

@@ -52,7 +52,7 @@
 #include "main.h"
 
 
-/* filepackages support for tracking packages owning a file. */
+/*** filepackages support for tracking packages owning a file. ***/
 
 #define PERFILEPACKAGESLUMP 10
 
@@ -107,7 +107,7 @@ filepackages_iter_free(struct filepackages_iterator *iter)
   free(iter);
 }
 
-/*** Generic data structures and routines ***/
+/*** Generic data structures and routines. ***/
 
 static bool allpackagesdone = false;
 static int nfiles= 0;
@@ -153,8 +153,7 @@ pkg_files_blank(struct pkginfo *pkg)
        current= current->next) {
     /* For each file that used to be in the package,
      * go through looking for this package's entry in the list
-     * of packages containing this file, and blank it out.
-     */
+     * of packages containing this file, and blank it out. */
     for (packageslump= current->namenode->packages;
          packageslump;
          packageslump= packageslump->more)
@@ -168,20 +167,18 @@ pkg_files_blank(struct pkginfo *pkg)
                findlast++);
           findlast--;
           /* findlast is now the last occupied entry, which may be the same as
-           * search.  We blank out the entry for this package.  We also
+           * search. We blank out the entry for this package. We also
            * have to copy the last entry into the empty slot, because
-           * the list is null-pointer-terminated.
-           */
+           * the list is NULL-pointer-terminated. */
           packageslump->pkgs[search]= packageslump->pkgs[findlast];
           packageslump->pkgs[findlast] = NULL;
-          /* This may result in an empty link in the list.  This is OK. */
+          /* This may result in an empty link in the list. This is OK. */
           goto xit_search_to_delete_from_perfilenodelist;
         }
   xit_search_to_delete_from_perfilenodelist:
     ;
     /* The actual filelist links were allocated using nfmalloc, so
-     * we shouldn't free them.
-     */
+     * we shouldn't free them. */
   }
   pkg->clientdata->files = NULL;
 }
@@ -298,11 +295,11 @@ ensure_packagefiles_available(struct pkginfo *pkg)
       if (!(ptr = memchr(thisline, '\n', loaded_list_end - thisline))) 
         ohshit(_("files list file for package '%.250s' is missing final newline"),
                pkg->name);
-      /* where to start next time around */
+      /* Where to start next time around. */
       nextline = ptr + 1;
-      /* strip trailing "/" */
+      /* Strip trailing ‘/’. */
       if (ptr > thisline && ptr[-1] == '/') ptr--;
-      /* add the file to the list */
+      /* Add the file to the list. */
       if (ptr == thisline)
         ohshit(_("files list file for package `%.250s' contains empty filename"),pkg->name);
       *ptr = '\0';
@@ -310,7 +307,7 @@ ensure_packagefiles_available(struct pkginfo *pkg)
       thisline = nextline;
     }
   }
-  pop_cleanup(ehflag_normaltidy); /* fd= open() */
+  pop_cleanup(ehflag_normaltidy); /* fd = open() */
   if (close(fd))
     ohshite(_("error closing files list file for package `%.250s'"),pkg->name);
 
@@ -455,13 +452,14 @@ void ensure_allinstfiles_available_quiet(void) {
   ensure_allinstfiles_available();
 }
 
+/*
+ * If leaveout is nonzero, will not write any file whose filenamenode
+ * has the fnnf_elide_other_lists flag set.
+ */
 void
 write_filelist_except(struct pkginfo *pkg, struct fileinlist *list,
                       bool leaveout)
 {
-  /* If leaveout is nonzero, will not write any file whose filenamenode
-   * has the fnnf_elide_other_lists flag set.
-   */
   static struct varbuf vb, newvb;
   FILE *file;
 
@@ -493,7 +491,7 @@ write_filelist_except(struct pkginfo *pkg, struct fileinlist *list,
     ohshite(_("failed to flush updated files list file for package %s"),pkg->name);
   if (fsync(fileno(file)))
     ohshite(_("failed to sync updated files list file for package %s"),pkg->name);
-  pop_cleanup(ehflag_normaltidy); /* file= fopen() */
+  pop_cleanup(ehflag_normaltidy); /* file = fopen() */
   if (fclose(file))
     ohshite(_("failed to close updated files list file for package %s"),pkg->name);
   if (rename(newvb.buf,vb.buf))
@@ -504,14 +502,15 @@ write_filelist_except(struct pkginfo *pkg, struct fileinlist *list,
   note_must_reread_files_inpackage(pkg);
 }
 
+/*
+ * Initializes an iterator that appears to go through the file
+ * list ‘files’ in reverse order, returning the namenode from
+ * each. What actually happens is that we walk the list here,
+ * building up a reverse list, and then peel it apart one
+ * entry at a time.
+ */
 void reversefilelist_init(struct reversefilelistiter *iterptr,
                           struct fileinlist *files) {
-  /* Initialises an iterator that appears to go through the file
-   * list `files' in reverse order, returning the namenode from
-   * each.  What actually happens is that we walk the list here,
-   * building up a reverse list, and then peel it apart one
-   * entry at a time.
-   */
   struct fileinlist *newent;
   
   iterptr->todo = NULL;
@@ -537,12 +536,13 @@ struct filenamenode *reversefilelist_next(struct reversefilelistiter *iterptr) {
   return ret;
 }
 
+/*
+ * Clients must call this function to clean up the reversefilelistiter
+ * if they wish to break out of the iteration before it is all done.
+ * Calling this function is not necessary if reversefilelist_next has
+ * been called until it returned 0.
+ */
 void reversefilelist_abort(struct reversefilelistiter *iterptr) {
-  /* Clients must call this function to clean up the reversefilelistiter
-   * if they wish to break out of the iteration before it is all done.
-   * Calling this function is not necessary if reversefilelist_next has
-   * been called until it returned 0.
-   */
   while (reversefilelist_next(iterptr));
 }
 
@@ -551,11 +551,9 @@ struct fileiterator {
   int nbinn;
 };
 
+/* This must always be a power of two. If you change it consider changing
+ * the per-character hashing factor (currently 1785 = 137 * 13) too. */
 #define BINS (1 << 17)
- /* This must always be a power of two.  If you change it
-  * consider changing the per-character hashing factor (currently
-  * 1785 = 137*13) too.
-  */
 
 static struct filenamenode *bins[BINS];
 
@@ -606,12 +604,13 @@ struct filenamenode *findnamenode(const char *name, enum fnnflags flags) {
   struct filenamenode **pointerp, *newnode;
   const char *orig_name = name;
 
-  /* We skip initial slashes and ./ pairs, and add our own single leading slash. */
+  /* We skip initial slashes and ‘./’ pairs, and add our own single
+   * leading slash. */
   name = path_skip_slash_dotslash(name);
 
   pointerp= bins + (hash(name) & (BINS-1));
   while (*pointerp) {
-/* Why is this assert nescessary?  It is checking already added entries. */
+    /* XXX: Why is the assert needed? It's checking already added entries. */
     assert((*pointerp)->name[0] == '/');
     if (!strcmp((*pointerp)->name+1,name)) break;
     pointerp= &(*pointerp)->next;

src/filesdb.h

@@ -26,33 +26,32 @@
 
 /*
  * Data structure here is as follows:
- * 
- * For each package we have a `struct fileinlist *', the head of
- * a list of files in that package.  They are in `forwards' order.
- * Each entry has a pointer to the `struct filenamenode'.
+ *
+ * For each package we have a ‘struct fileinlist *’, the head of a list of
+ * files in that package. They are in ‘forwards’ order. Each entry has a
+ * pointer to the ‘struct filenamenode’.
  *
  * The struct filenamenodes are in a hash table, indexed by name.
  * (This hash table is not visible to callers.)
  *
- * Each filenamenode has a (possibly empty) list of `struct
- * filepackage', giving a list of the packages listing that
- * filename.
+ * Each filenamenode has a (possibly empty) list of ‘struct filepackage’,
+ * giving a list of the packages listing that filename.
  *
- * When we read files contained info about a particular package
- * we set the `files' member of the clientdata struct to the
- * appropriate thing.  When not yet set the files pointer is
- * made to point to `fileslist_uninited' (this is available only
- * internally, withing filesdb.c - the published interface is
- * ensure_*_available).
+ * When we read files contained info about a particular package we set the
+ * ‘files’ member of the clientdata struct to the appropriate thing. When
+ * not yet set the files pointer is made to point to ‘fileslist_uninited’
+ * (this is available only internally, withing filesdb.c - the published
+ * interface is ensure_*_available).
  */
 
 struct pkginfo;
 
-/* flags to findnamenode() */
-
+/* Flags to findnamenode(). */
 enum fnnflags {
-    fnn_nocopy=                 000001, /* do not need to copy filename */
-    fnn_nonew =                 000002, /* findnamenode may return NULL */
+    /* Do not need to copy filename. */
+    fnn_nocopy = 000001,
+    /* findnamenode may return NULL. */
+    fnn_nonew = 000002,
 };
 
 struct filenamenode {
@@ -68,22 +67,36 @@ struct filenamenode {
    * This functionality used to be in the suidmanager package. */
   struct file_stat *statoverride;
 
-  /* Fields from here on are used by archives.c &c, and cleared by
+  /*
+   * Fields from here on are used by archives.c &c, and cleared by
    * filesdbinit.
    */
+
+  /* Set to zero when a new node is created. */
   enum {
-    fnnf_new_conff=           000001, /* in the newconffiles list */
-    fnnf_new_inarchive=       000002, /* in the new filesystem archive */
-    fnnf_old_conff=           000004, /* in the old package's conffiles list */
-    fnnf_obs_conff=           000100, /* obsolete conffile */
-    fnnf_elide_other_lists=   000010, /* must remove from other packages' lists */
-    fnnf_no_atomic_overwrite= 000020, /* >=1 instance is a dir, cannot rename over */
-    fnnf_placed_on_disk=      000040, /* new file has been placed on the disk */
-    fnnf_deferred_fsync =     000200,
-    fnnf_deferred_rename =    000400,
-    fnnf_filtered =           001000, /* path being filtered */
-  } flags; /* Set to zero when a new node is created. */
-  const char *oldhash; /* valid iff this namenode is in the newconffiles list */
+    /* In the newconffiles list. */
+    fnnf_new_conff = 000001,
+    /* In the new filesystem archive. */
+    fnnf_new_inarchive = 000002,
+    /* In the old package's conffiles list. */
+    fnnf_old_conff = 000004,
+    /* Obsolete conffile. */
+    fnnf_obs_conff = 000100,
+    /* Must remove from other packages' lists. */
+    fnnf_elide_other_lists = 000010,
+    /* >= 1 instance is a dir, cannot rename over. */
+    fnnf_no_atomic_overwrite = 000020,
+    /* New file has been placed on the disk. */
+    fnnf_placed_on_disk = 000040,
+    fnnf_deferred_fsync = 000200,
+    fnnf_deferred_rename = 000400,
+    /* Path being filtered. */
+    fnnf_filtered = 001000,
+  } flags;
+
+  /* Valid iff this namenode is in the newconffiles list. */
+  const char *oldhash;
+
   struct stat *filestat;
   struct trigfileint *trig_interested;
 };
@@ -93,29 +106,30 @@ struct fileinlist {
   struct filenamenode *namenode;
 };
 
+/*
+ * When we deal with an ‘overridden’ file, every package except the
+ * overriding one is considered to contain the other file instead. Both
+ * files have entries in the filesdb database, and they refer to each other
+ * via these diversion structures.
+ *
+ * The contested filename's filenamenode has an diversion entry with
+ * useinstead set to point to the redirected filename's filenamenode; the
+ * redirected filenamenode has camefrom set to the contested filenamenode.
+ * Both sides' diversion entries will have pkg set to the package (if any)
+ * which is allowed to use the contended filename.
+ *
+ * Packages that contain either version of the file will all refer to the
+ * contested filenamenode in their per-file package lists (both in core and
+ * on disk). References are redirected to the other filenamenode's filename
+ * where appropriate.
+ */
 struct diversion {
-  /* When we deal with an `overridden' file, every package except
-   * the overriding one is considered to contain the other file
-   * instead.  Both files have entries in the filesdb database, and
-   * they refer to each other via these diversion structures.
-   *
-   * The contested filename's filenamenode has an diversion entry
-   * with useinstead set to point to the redirected filename's
-   * filenamenode; the redirected filenamenode has camefrom set to the
-   * contested filenamenode.  Both sides' diversion entries will
-   * have pkg set to the package (if any) which is allowed to use the
-   * contended filename.
-   *
-   * Packages that contain either version of the file will all
-   * refer to the contested filenamenode in their per-file package lists
-   * (both in core and on disk).  References are redirected to the other
-   * filenamenode's filename where appropriate.
-   */
   struct filenamenode *useinstead;
   struct filenamenode *camefrom;
   struct pkginfo *pkg;
+
+  /* The ‘contested’ halves are in this list for easy cleanup. */
   struct diversion *next;
-  /* The `contested' halves are in this list for easy cleanup. */
 };
 
 struct filepackages_iterator;

src/help.c

@@ -80,8 +80,10 @@ struct filenamenode *namenodetouse(struct filenamenode *namenode, struct pkginfo
   return r;
 }
 
+/**
+ * Verify that some programs can be found in the PATH.
+ */
 void checkpath(void) {
-/* Verify that some programs can be found in the PATH. */
   static const char *const prog_list[] = {
     DEFAULTSHELL,
     RM,
@@ -174,13 +176,15 @@ force_conflicts(struct deppossi *possi)
   return fc_conflicts;
 }
 
+/**
+ * Returns the path to the script inside the chroot.
+ *
+ * FIXME: None of the stuff here will work if admindir isn't inside
+ * instdir as expected.
+ */
 static const char *
 preexecscript(struct command *cmd)
 {
-  /* returns the path to the script inside the chroot
-   * FIXME: none of the stuff here will work if admindir isn't inside
-   * instdir as expected.
-   */
   size_t instdirl;
 
   if (*instdir) {
@@ -270,7 +274,7 @@ do_script(struct pkginfo *pkg, struct pkginfoperfile *pif,
     cmd->filename = cmd->argv[0] = preexecscript(cmd);
     command_exec(cmd);
   }
-  subproc_signals_setup(cmd->name); /* This does a push_cleanup() */
+  subproc_signals_setup(cmd->name); /* This does a push_cleanup(). */
   r = subproc_wait_check(c1, cmd->name, warn);
   pop_cleanup(ehflag_normaltidy);
 
@@ -311,7 +315,10 @@ vmaintainer_script_installed(struct pkginfo *pkg, const char *scriptname,
   return 1;
 }
 
-/* All ...'s are const char*'s. */
+/*
+ * All ...'s in maintainer_script_* are const char *'s.
+ */
+
 int
 maintainer_script_installed(struct pkginfo *pkg, const char *scriptname,
                             const char *desc, ...)
@@ -568,17 +575,17 @@ void ensure_pathname_nonexisting(const char *pathname) {
   assert(*u);
 
   debug(dbg_eachfile,"ensure_pathname_nonexisting `%s'",pathname);
-  if (!rmdir(pathname)) return; /* Deleted it OK, it was a directory. */
+  if (!rmdir(pathname))
+    return; /* Deleted it OK, it was a directory. */
   if (errno == ENOENT || errno == ELOOP) return;
   if (errno == ENOTDIR) {
-    /* Either it's a file, or one of the path components is.  If one
-     * of the path components is this will fail again ...
-     */
+    /* Either it's a file, or one of the path components is. If one
+     * of the path components is this will fail again ... */
     if (secure_unlink(pathname) == 0)
-      return; /* OK, it was */
+      return; /* OK, it was. */
     if (errno == ENOTDIR) return;
   }
-  if (errno != ENOTEMPTY && errno != EEXIST) { /* Huh ? */
+  if (errno != ENOTEMPTY && errno != EEXIST) { /* Huh? */
     ohshite(_("unable to securely remove '%.255s'"), pathname);
   }
   c1 = subproc_fork();

src/main.c

@@ -66,10 +66,13 @@ printversion(const struct cmdinfo *ci, const char *value)
 
   exit(0);
 }
+
 /*
-   options that need fixing:
-  dpkg --yet-to-unpack                 \n\
-  */
+ * FIXME: Options that need fixing:
+ * dpkg --yet-to-unpack
+ * dpkg --command-fd
+ */
+
 static void DPKG_ATTR_NORET
 usage(const struct cmdinfo *ci, const char *value)
 {
@@ -176,7 +179,6 @@ int f_pending=0, f_recursive=0, f_alsoselect=1, f_skipsame=0, f_noact=0;
 int f_autodeconf=0, f_nodebsig=0;
 int f_triggers = 0;
 unsigned long f_debug=0;
-/* Change fc_overwrite to 1 to enable force-overwrite by default */
 int fc_downgrade=1, fc_configureany=0, fc_hold=0, fc_removereinstreq=0, fc_overwrite=0;
 int fc_removeessential=0, fc_conflicts=0, fc_depends=0, fc_dependsversion=0;
 int fc_breaks=0, fc_badpath=0, fc_overwritediverted=0, fc_architecture=0;
@@ -447,11 +449,11 @@ static void setforce(const struct cmdinfo *cip, const char *value) {
 
 void execbackend(const char *const *argv) DPKG_ATTR_NORET;
 void commandfd(const char *const *argv);
+
+/* This table has both the action entries in it and the normal options.
+ * The action entries are made with the ACTION macro, as they all
+ * have a very similar structure. */
 static const struct cmdinfo cmdinfos[]= {
-  /* This table has both the action entries in it and the normal options.
-   * The action entries are made with the ACTION macro, as they all
-   * have a very similar structure.
-   */
 #define ACTIONBACKEND(longopt, shortopt, backend) \
  { longopt, shortopt, 0, NULL, NULL, setaction, 0, (void *)backend, (void_func *)execbackend }
 
@@ -540,10 +542,9 @@ void execbackend(const char *const *argv) {
   command_init(&cmd, cipaction->parg, NULL);
   command_add_arg(&cmd, cipaction->parg);
 
-  /*
-   * Special case: dpkg-query takes the --admindir option, and if dpkg itself
-   * was given a different admin directory, we need to pass it along to it.
-   */
+  /* Special case: dpkg-query takes the --admindir option, and if dpkg
+   * itself was given a different admin directory, we need to pass it
+   * along to it. */
   if (strcmp(cipaction->parg, DPKGQUERY) == 0 &&
       strcmp(admindir, ADMINDIR) != 0) {
     arg = m_malloc((strlen("--admindir=") + strlen(admindir) + 1));
@@ -604,7 +605,10 @@ void commandfd(const char *const *argv) {
       varbufaddc(&linevb,c);
       c= getc(in);
       if (c == '\n') lno++;
-      if (isspace(c)) argc++;  /* This isn't fully accurate, but overestimating can't hurt. */
+
+      /* This isn't fully accurate, but overestimating can't hurt. */
+      if (isspace(c))
+        argc++;
     } while (c != EOF && c != '\n');
     if (c == EOF) ohshit(_("unexpected eof before end of line %d"),lno);
     if (!argc) continue;
@@ -639,11 +643,10 @@ void commandfd(const char *const *argv) {
     *ptr = '\0';
     newargs[argc++] = NULL;
 
-/* We strdup each argument, but never free it, because the error messages
- * contain references back to these strings.  Freeing them, and reusing
- * the memory, would make those error messages confusing, to say the
- * least.
- */
+    /* We strdup() each argument, but never free it, because the
+     * error messages contain references back to these strings.
+     * Freeing them, and reusing the memory, would make those
+     * error messages confusing, to say the least. */
     for(i=1;i<argc;i++)
       if (newargs[i])
         newargs[i] = m_strdup(newargs[i]);

src/main.h

@@ -23,7 +23,8 @@
 
 #include <dpkg/pkg-list.h>
 
-struct fileinlist; /* these two are defined in filesdb.h */
+/* These two are defined in filesdb.h. */
+struct fileinlist;
 struct filenamenode;
 
 struct perpackagestate {
@@ -38,13 +39,14 @@ struct perpackagestate {
     black,
   } color;
 
-  /*   filelistvalid   files         meaning
-   *       0             0           not read yet, must do so if want them
-   *       0            !=0          read, but rewritten and now out of
-   *                               date.  If want info must throw away old
-   *                               and reread file.
-   *       1            !=0          read, all is OK
-   *       1             0           read OK, but, there were no files
+  /*
+   * filelistvalid  files  Meaning
+   * -------------  -----  -------
+   * false          NULL   Not read yet, must do so if want them.
+   * false          !NULL  Read, but rewritten and now out of date. If want
+   *                         info must throw away old and reread file.
+   * true           !NULL  Read, all is OK.
+   * true           NULL   Read OK, but, there were no files.
    */
   bool fileslistvalid;
   struct fileinlist *files;
@@ -184,7 +186,7 @@ void packages(const char *const *argv);
 void removal_bulk(struct pkginfo *pkg);
 int conffderef(struct pkginfo *pkg, struct varbuf *result, const char *in);
 int dependencies_ok(struct pkginfo *pkg, struct pkginfo *removing,
-                    struct varbuf *aemsgs); /* checks [Pre]-Depends only */
+                    struct varbuf *aemsgs);
 int breakses_ok(struct pkginfo *pkg, struct varbuf *aemsgs);
 
 void deferred_remove(struct pkginfo *pkg);
@@ -221,7 +223,6 @@ void checkpath(void);
 
 struct filenamenode *namenodetouse(struct filenamenode*, struct pkginfo*);
 
-/* all ...'s are const char*'s ... */
 int maintainer_script_installed(struct pkginfo *pkg, const char *scriptname,
                                 const char *desc, ...) DPKG_ATTR_SENTINEL;
 int maintainer_script_new(struct pkginfo *pkg,
@@ -270,11 +271,8 @@ void trigproc_install_hooks(void);
 void trigproc_run_deferred(void);
 void trigproc_reset_cycle(void);
 
-/* Does cycle checking. Doesn't mind if pkg has no triggers
- * pending - in that case does nothing but fix up any stale awaiters. */
 void trigproc(struct pkginfo *pkg);
 
-/* Called by modstatdb_note. */
 void trig_activate_packageprocessing(struct pkginfo *pkg);
 
 /* from depcon.c */

src/packages.c

@@ -194,7 +194,8 @@ void process_queue(void) {
   
   while (!pkg_queue_is_empty(&queue)) {
     pkg = pkg_queue_pop(&queue);
-    if (!pkg) continue; /* duplicate, which we removed earlier */
+    if (!pkg)
+      continue; /* Duplicate, which we removed earlier. */
 
     action_todo = cipaction->arg;
 
@@ -213,7 +214,8 @@ void process_queue(void) {
     assert(pkg->status <= stat_installed);
 
     if (setjmp(ejbuf)) {
-      /* give up on it from the point of view of other packages, ie reset istobe */
+      /* Give up on it from the point of view of other packages, i.e. reset
+       * istobe. */
       pkg->clientdata->istobe= itb_normal;
 
       pop_error_context(ehflag_bombout);
@@ -256,33 +258,33 @@ void process_queue(void) {
   assert(!queue.length);
 }    
 
-/*** dependency processing - common to --configure and --remove ***/
+/*** Dependency processing - common to --configure and --remove. ***/
 
 /*
  * The algorithm for deciding what to configure or remove first is as
  * follows:
  *
- * Loop through all packages doing a `try 1' until we've been round and
- * nothing has been done, then do `try 2' and `try 3' likewise.
+ * Loop through all packages doing a ‘try 1’ until we've been round and
+ * nothing has been done, then do ‘try 2’ and ‘try 3’ likewise.
  *
  * When configuring, in each try we check to see whether all
- * dependencies of this package are done.  If so we do it.  If some of
+ * dependencies of this package are done. If so we do it. If some of
  * the dependencies aren't done yet but will be later we defer the
  * package, otherwise it is an error.
  *
  * When removing, in each try we check to see whether there are any
  * packages that would have dependencies missing if we removed this
- * one.  If not we remove it now.  If some of these packages are
+ * one. If not we remove it now. If some of these packages are
  * themselves scheduled for removal we defer the package until they
  * have been done.
  *
  * The criteria for satisfying a dependency vary with the various
- * tries.  In try 1 we treat the dependencies as absolute.  In try 2 we
+ * tries. In try 1 we treat the dependencies as absolute. In try 2 we
  * check break any cycles in the dependency graph involving the package
  * we are trying to process before trying to process the package
- * normally.  In try 3 (which should only be reached if
+ * normally. In try 3 (which should only be reached if
  * --force-depends-version is set) we ignore version number clauses in
- * Depends lines.  In try 4 (only reached if --force-depends is set) we
+ * Depends lines. In try 4 (only reached if --force-depends is set) we
  * say "ok" regardless.
  *
  * If we are configuring and one of the packages we depend on is
@@ -293,15 +295,16 @@ void process_queue(void) {
  * and breaking.
  */
 
-/* Return values:
+/*
+ * Return values:
  *   0: cannot be satisfied.
  *   1: defer: may be satisfied later, when other packages are better or
  *      at higher dependtry due to --force
  *      will set *fixbytrig to package whose trigger processing would help
- *      if applicable (and leave it alone otherwise)
+ *      if applicable (and leave it alone otherwise).
  *   2: not satisfied but forcing
- *      (*interestingwarnings >= 0 on exit? caller is to print oemsgs)
- *   3: satisfied now
+ *      (*interestingwarnings >= 0 on exit? caller is to print oemsgs).
+ *   3: satisfied now.
  */
 static int deppossi_ok_found(struct pkginfo *possdependee,
                              struct pkginfo *requiredby,
@@ -377,12 +380,11 @@ static int deppossi_ok_found(struct pkginfo *possdependee,
        * the named package doesn't actually have any pending triggers. In
        * that case we queue the non-pending package for trigger processing
        * anyway, and that trigger processing will be a noop except for
-       * sorting out all of the packages which name it in T-Awaited.
+       * sorting out all of the packages which name it in Triggers-Awaited.
        *
        * (This situation can only arise if modstatdb_note success in
        * clearing the triggers-pending status of the pending package
-       * but then fails to go on to update the awaiters.)
-       */
+       * but then fails to go on to update the awaiters.) */
       *fixbytrig = possdependee->trigaw.head->pend;
       debug(dbg_depcondetail,
             "      triggers-awaited, fixbytrig `%s', returning 1",
@@ -510,9 +512,16 @@ int breakses_ok(struct pkginfo *pkg, struct varbuf *aemsgs) {
   return ok;
 }
 
+/*
+ * Checks [Pre]-Depends only.
+ */
 int dependencies_ok(struct pkginfo *pkg, struct pkginfo *removing,
                     struct varbuf *aemsgs) {
-  int ok, found, thisf, interestingwarnings;
+  /* Valid values: 2 = ok, 1 = defer, 0 = halt. */
+  int ok;
+  /* Valid values: 0 = none, 1 = defer, 2 = withwarning, 3 = ok. */
+  int found, thisf;
+  int interestingwarnings;
   bool matched, anycannotfixbytrig;
   struct varbuf oemsgs = VARBUF_INIT;
   struct dependency *dep;
@@ -520,7 +529,7 @@ int dependencies_ok(struct pkginfo *pkg, struct pkginfo *removing,
   struct pkginfo *possfixbytrig, *canfixbytrig;
 
   interestingwarnings= 0;
-  ok= 2; /* 2=ok, 1=defer, 0=halt */
+  ok = 2;
   debug(dbg_depcon,"checking dependencies of %s (- %s)",
         pkg->name, removing ? removing->name : "<none>");
 
@@ -531,7 +540,7 @@ int dependencies_ok(struct pkginfo *pkg, struct pkginfo *removing,
     debug(dbg_depcondetail,"  checking group ...");
     matched = false;
     varbufreset(&oemsgs);
-    found= 0; /* 0=none, 1=defer, 2=withwarning, 3=ok */
+    found = 0;
     possfixbytrig = NULL;
     for (possi= dep->list; found != 3 && possi; possi= possi->next) {
       debug(dbg_depcondetail,"    checking possibility  -> %s",possi->ed->name);
@@ -575,8 +584,7 @@ int dependencies_ok(struct pkginfo *pkg, struct pkginfo *removing,
       varbufdependency(aemsgs, dep);
       if (interestingwarnings) {
         /* Don't print the line about the package to be removed if
-         * that's the only line.
-         */
+         * that's the only line. */
         varbufaddstr(aemsgs, _("; however:\n"));
         varbufaddc(&oemsgs, 0);
         varbufaddstr(aemsgs, oemsgs.buf);

src/processarc.c

@@ -93,8 +93,7 @@ void process_archive(const char *filename) {
   /* These need to be static so that we can pass their addresses to
    * push_cleanup as arguments to the cu_xxx routines; if an error occurs
    * we unwind the stack before processing the cleanup list, and these
-   * variables had better still exist ...
-   */
+   * variables had better still exist ... */
   static int p1[2];
   static char *cidirbuf = NULL, *reasmbuf = NULL;
   static struct fileinlist *newconffiles, *newfileslist;
@@ -134,7 +133,7 @@ void process_archive(const char *filename) {
   if (!f_noact) {
     int status;
 
-    /* We can't `tentatively-reassemble' packages. */
+    /* We can't ‘tentatively-reassemble’ packages. */
     if (!reasmbuf) {
       reasmbuf= m_malloc(admindirlen+sizeof(REASSEMBLETMP)+5);
       strcpy(reasmbuf,admindir);
@@ -152,12 +151,13 @@ void process_archive(const char *filename) {
     status = subproc_wait(c1, SPLITTER);
     switch (WIFEXITED(status) ? WEXITSTATUS(status) : -1) {
     case 0:
-      /* It was a part - is it complete ? */
+      /* It was a part - is it complete? */
       if (!stat(reasmbuf,&stab)) { /* Yes. */
         filename= reasmbuf;
         pfilename= _("reassembled package file");
         break;
-      } else if (errno == ENOENT) { /* No.  That's it, we skip it. */
+      } else if (errno == ENOENT) {
+        /* No. That's it, we skip it. */
         return;
       }
     case 1:
@@ -205,8 +205,7 @@ void process_archive(const char *filename) {
     cidirrest = cidir + strlen(cidir);
   } else {
     /* We want it to be on the same filesystem so that we can
-     * use rename(2) to install the postinst &c.
-     */
+     * use rename(2) to install the postinst &c. */
     if (!cidirbuf)
       cidirbuf= m_malloc(admindirlen+sizeof(CONTROLDIRTMP)+MAXCONTROLFILENAME+10);
     cidir= cidirbuf;
@@ -247,7 +246,8 @@ void process_archive(const char *filename) {
     pkg->files->next = NULL;
     pkg->files->name = pkg->files->msdosname = pkg->files->md5sum = NULL;
   }
-  /* Always nfmalloc.  Otherwise, we may overwrite some other field(like md5sum). */
+  /* Always nfmalloc. Otherwise, we may overwrite some other field (like
+   * md5sum). */
   psize = nfmalloc(30);
   sprintf(psize, "%lu", (unsigned long)stab.st_size);
   pkg->files->size = psize;
@@ -280,7 +280,7 @@ void process_archive(const char *filename) {
   }
 
   /* Check if anything is installed that we conflict with, or not installed
-   * that we need */
+   * that we need. */
   pkg->clientdata->istobe= itb_installnew;
 
   for (dsearch= pkg->available.depends; dsearch; dsearch= dsearch->next) {
@@ -378,17 +378,16 @@ void process_archive(const char *filename) {
       namenode->oldhash= NEWCONFFILEFLAG;
       newconff= newconff_append(&newconffileslastp, namenode);
       
-      /* Let's see if any packages have this file.  If they do we
+      /* Let's see if any packages have this file. If they do we
        * check to see if they listed it as a conffile, and if they did
-       * we copy the hash across.  Since (for plain file conffiles,
+       * we copy the hash across. Since (for plain file conffiles,
        * which is the only kind we are supposed to have) there will
-       * only be one package which `has' the file, this will usually
+       * only be one package which ‘has’ the file, this will usually
        * mean we only look in the package which we're installing now.
-       * The `conffiles' data in the status file is ignored when a
+       * The ‘conffiles’ data in the status file is ignored when a
        * package isn't also listed in the file ownership database as
-       * having that file.  If several packages are listed as owning
-       * the file we pick one at random.
-       */
+       * having that file. If several packages are listed as owning
+       * the file we pick one at random. */
       searchconff = NULL;
 
       iter = filepackages_iter_new(newconff->namenode);
@@ -416,7 +415,7 @@ void process_archive(const char *filename) {
 
       if (searchconff) {
         newconff->namenode->oldhash= searchconff->hash;
-	/* we don't copy `obsolete'; it's not obsolete in the new package */
+	/* We don't copy ‘obsolete’; it's not obsolete in the new package. */
       } else {
         debug(dbg_conff,"process_archive conffile `%s' no package, no hash",
               newconff->namenode->name);
@@ -424,15 +423,14 @@ void process_archive(const char *filename) {
       newconff->namenode->flags |= fnnf_new_conff;
     }
     if (ferror(conff)) ohshite(_("read error in %.250s"),cidir);
-    pop_cleanup(ehflag_normaltidy); /* conff= fopen() */
+    pop_cleanup(ehflag_normaltidy); /* conff = fopen() */
     if (fclose(conff)) ohshite(_("error closing %.250s"),cidir);
   } else {
     if (errno != ENOENT) ohshite(_("error trying to open %.250s"),cidir);
   }
 
   /* All the old conffiles are marked with a flag, so that we don't delete
-   * them if they seem to disappear completely.
-   */
+   * them if they seem to disappear completely. */
   oldconffsetflags(pkg->installed.conffiles);
   for (i = 0 ; i < cflict_index ; i++) {
     oldconffsetflags(conflictor[i]->installed.conffiles);
@@ -474,8 +472,7 @@ void process_archive(const char *filename) {
 
     /* This means that we *either* go and run postinst abort-deconfigure,
      * *or* queue the package for later configure processing, depending
-     * on which error cleanup route gets taken.
-     */
+     * on which error cleanup route gets taken. */
     push_cleanup(cu_prermdeconfigure, ~ehflag_normaltidy,
                  ok_prermdeconfigure, ehflag_normaltidy,
                  3, (void*)deconpil->pkg, (void*)removing, (void*)pkg);
@@ -548,27 +545,28 @@ void process_archive(const char *filename) {
    * Now we unpack the archive, backing things up as we go.
    * For each file, we check to see if it already exists.
    * There are several possibilities:
+   *
    * + We are trying to install a non-directory ...
-   *  - It doesn't exist.  In this case we simply extract it.
-   *  - It is a plain file, device, symlink, &c.  We do an `atomic
-   *    overwrite' using link() and rename(), but leave a backup copy.
+   *  - It doesn't exist. In this case we simply extract it.
+   *  - It is a plain file, device, symlink, &c. We do an ‘atomic
+   *    overwrite’ using link() and rename(), but leave a backup copy.
    *    Later, when we delete the backup, we remove it from any other
    *    packages' lists.
    *  - It is a directory. In this case it depends on whether we're
    *    trying to install a symlink or something else.
    *   = If we're not trying to install a symlink we move the directory
-   *     aside and extract the node.  Later, when we recursively remove
+   *     aside and extract the node. Later, when we recursively remove
    *     the backed-up directory, we remove it from any other packages'
    *     lists.
    *   = If we are trying to install a symlink we do nothing - ie,
-   *     dpkg will never replace a directory tree with a symlink.  This
+   *     dpkg will never replace a directory tree with a symlink. This
    *     is to avoid embarrassing effects such as replacing a directory
    *     tree with a link to a link to the original directory tree.
    * + We are trying to install a directory ...
-   *  - It doesn't exist.  We create it with the appropriate modes.
-   *  - It exists as a directory or a symlink to one.  We do nothing.
+   *  - It doesn't exist. We create it with the appropriate modes.
+   *  - It exists as a directory or a symlink to one. We do nothing.
    *  - It is a plain file or a symlink (other than to a directory).
-   *    We move it aside and create the directory.  Later, when we
+   *    We move it aside and create the directory. Later, when we
    *    delete the backup, we remove it from any other packages' lists.
    *
    *                   Install non-dir   Install symlink   Install dir
@@ -584,13 +582,14 @@ void process_archive(const char *filename) {
    * 
    * After we've done this we go through the remaining things in the
    * lists of packages we're trying to remove (including the old
-   * version of the current package).  This happens in reverse order,
+   * version of the current package). This happens in reverse order,
    * so that we process files before the directories (or symlinks-to-
    * directories) containing them.
+   *
    * + If the thing is a conffile then we leave it alone for the purge
    *   operation.
    * + Otherwise, there are several possibilities too:
-   *  - The listed thing does not exist.  We ignore it.
+   *  - The listed thing does not exist. We ignore it.
    *  - The listed thing is a directory or a symlink to a directory.
    *    We delete it only if it isn't listed in any other package.
    *  - The listed thing is not a directory, but was part of the package
@@ -598,22 +597,23 @@ void process_archive(const char *filename) {
    *    same ones from the old package by checking dev/inode
    *  - The listed thing is not a directory or a symlink to one (ie,
    *    it's a plain file, device, pipe, &c, or a symlink to one, or a
-   *    dangling symlink).  We delete it.
+   *    dangling symlink). We delete it.
+   *
    * The removed packages' list becomes empty (of course, the new
    * version of the package we're installing will have a new list,
    * which replaces the old version's list).
    *
    * If at any stage we remove a file from a package's list, and the
    * package isn't one we're already processing, and the package's
-   * list becomes empty as a result, we `vanish' the package.  This
-   * means that we run its postrm with the `disappear' argument, and
-   * put the package in the `not-installed' state.  If it had any
+   * list becomes empty as a result, we ‘vanish’ the package. This
+   * means that we run its postrm with the ‘disappear’ argument, and
+   * put the package in the ‘not-installed’ state. If it had any
    * conffiles, their hashes and ownership will have been transferred
    * already, so we just ignore those and forget about them from the
    * point of view of the disappearing package.
    *
    * NOTE THAT THE OLD POSTRM IS RUN AFTER THE NEW PREINST, since the
-   * files get replaced `as we go'.
+   * files get replaced ‘as we go’.
    */
 
   m_pipe(p1);
@@ -650,9 +650,8 @@ void process_archive(const char *filename) {
   tar_deferred_extract(newfileslist, pkg);
 
   if (oldversionstatus == stat_halfinstalled || oldversionstatus == stat_unpacked) {
-    /* Packages that were in `installed' and `postinstfailed' have been reduced
-     * to `unpacked' by now, by the running of the prerm script.
-     */
+    /* Packages that were in ‘installed’ and ‘postinstfailed’ have been
+     * reduced to ‘unpacked’ by now, by the running of the prerm script. */
     pkg->status= stat_halfinstalled;
     modstatdb_note(pkg);
     push_cleanup(cu_postrmupgrade, ~ehflag_normaltidy, NULL, 0, 1, (void *)pkg);
@@ -661,26 +660,24 @@ void process_archive(const char *filename) {
   }
 
   /* If anything goes wrong while tidying up it's a bit late to do
-   * anything about it.  However, we don't install the new status
+   * anything about it. However, we don't install the new status
    * info yet, so that a future dpkg installation will put everything
    * right (we hope).
    *
-   * If something does go wrong later the `conflictor' package will be
-   * left in the `removal_failed' state.  Removing or installing it
+   * If something does go wrong later the ‘conflictor’ package will be
+   * left in the ‘removal_failed’ state. Removing or installing it
    * will be impossible if it was required because of the conflict with
    * the package we're installing now and (presumably) the dependency
-   * by other packages.  This means that the files it contains in
+   * by other packages. This means that the files it contains in
    * common with this package will hang around until we successfully
    * get this package installed, after which point we can trust the
    * conflicting package's file list, which will have been updated to
-   * remove any files in this package.
-   */
+   * remove any files in this package. */
   push_checkpoint(~ehflag_bombout, ehflag_normaltidy);
   
   /* Now we delete all the files that were in the old version of
    * the package only, except (old or new) conffiles, which we leave
-   * alone.
-   */
+   * alone. */
   reversefilelist_init(&rlistit,pkg->clientdata->files);
   while ((namenode= reversefilelist_next(&rlistit))) {
     struct filenamenode *usenode;
@@ -717,7 +714,12 @@ void process_archive(const char *filename) {
 	          "(and has now been deleted)"), namenode->name);
       }
     } else {
-      /* Ok, it's an old file, but is it really not in the new package?
+      struct fileinlist *sameas = NULL;
+      static struct stat empty_stat;
+      struct varbuf cfilename = VARBUF_INIT;
+
+      /*
+       * Ok, it's an old file, but is it really not in the new package?
        * It might be known by a different name because of symlinks.
        *
        * We need to check to make sure, so we stat the file, then compare
@@ -730,13 +732,9 @@ void process_archive(const char *filename) {
        * the process a little leaner. We are only worried about new ones
        * since ones that stayed the same don't really apply here.
        */
-      struct fileinlist *sameas = NULL;
-      static struct stat empty_stat;
-      struct varbuf cfilename = VARBUF_INIT;
 
       /* If we can't stat the old or new file, or it's a directory,
-       * we leave it up to the normal code
-       */
+       * we leave it up to the normal code. */
       debug(dbg_eachfile, "process_archive: checking %s for same files on "
 	    "upgrade/downgrade", fnamevb.buf);
 
@@ -817,14 +815,12 @@ void process_archive(const char *filename) {
   }
 
   /* OK, now we can write the updated files-in-this package list,
-   * since we've done away (hopefully) with all the old junk.
-   */
+   * since we've done away (hopefully) with all the old junk. */
   write_filelist_except(pkg,newfileslist,0);
 
   /* Trigger interests may have changed.
    * Firstly we go through the old list of interests deleting them.
-   * Then we go through the new list adding them.
-   */
+   * Then we go through the new list adding them. */
   strcpy(cidirrest, TRIGGERSCIFILE);
   trig_parse_ci(pkgadminfile(pkg, TRIGGERSCIFILE),
                 trig_cicb_interest_delete, NULL, pkg);
@@ -832,11 +828,10 @@ void process_archive(const char *filename) {
   trig_file_interests_save();
 
   /* We also install the new maintainer scripts, and any other
-   * cruft that may have come along with the package.  First
+   * cruft that may have come along with the package. First
    * we go through the existing scripts replacing or removing
    * them as appropriate; then we go through the new scripts
-   * (any that are left) and install them.
-   */
+   * (any that are left) and install them. */
   debug(dbg_general, "process_archive updating info directory");
   varbufreset(&infofnvb);
   varbufaddstr(&infofnvb, pkgadmindir());
@@ -847,14 +842,23 @@ void process_archive(const char *filename) {
   push_cleanup(cu_closedir, ~0, NULL, 0, 1, (void *)dsd);
   while ((de = readdir(dsd)) != NULL) {
     debug(dbg_veryverbose, "process_archive info file `%s'", de->d_name);
-    if (de->d_name[0] == '.') continue; /* ignore dotfiles, including `.' and `..' */
-    p= strrchr(de->d_name,'.'); if (!p) continue; /* ignore anything odd */
+    /* Ignore dotfiles, including ‘.’ and ‘..’. */
+    if (de->d_name[0] == '.')
+      continue;
+    /* Ignore anything odd. */
+    p = strrchr(de->d_name, '.');
+    if (!p)
+      continue;
     if (strlen(pkg->name) != (size_t)(p-de->d_name) ||
         strncmp(de->d_name,pkg->name,p-de->d_name)) continue;
     debug(dbg_stupidlyverbose, "process_archive info this pkg");
-    /* Right do we have one ? */
-    p++; /* skip past the full stop */
-    if (!strcmp(p,LISTFILE)) continue; /* We do the list separately */
+    /* Right, do we have one? */
+
+    /* Skip past the full stop. */
+    p++;
+    /* We do the list separately. */
+    if (!strcmp(p, LISTFILE))
+      continue;
     if (strlen(p) > MAXCONTROLFILENAME)
       ohshit(_("old version of package has overly-long info file name starting `%.250s'"),
              de->d_name);
@@ -894,7 +898,8 @@ void process_archive(const char *filename) {
     free(rename_node);
   }
   
-  *cidirrest = '\0'; /* the directory itself */
+  /* The directory itself. */
+  *cidirrest = '\0';
   dsd= opendir(cidir);
   if (!dsd) ohshite(_("unable to open temp control directory"));
   push_cleanup(cu_closedir, ~0, NULL, 0, 1, (void *)dsd);
@@ -913,9 +918,10 @@ void process_archive(const char *filename) {
       ohshit(_("package control info contained directory `%.250s'"),cidir);
     else if (errno != ENOTDIR)
       ohshite(_("package control info rmdir of `%.250s' didn't say not a dir"),de->d_name);
+    /* Ignore the control file. */
     if (!strcmp(de->d_name,CONTROLFILE)) {
       debug(dbg_scripts,"process_archive tmp.ci script/file `%s' is control",cidir);
-      continue; /* ignore the control file */
+      continue;
     }
     if (!strcmp(de->d_name,LISTFILE)) {
       warning(_("package %s contained list as info file"), pkg->name);
@@ -935,9 +941,11 @@ void process_archive(const char *filename) {
 
   pop_cleanup(ehflag_normaltidy); /* closedir */
 
-  /* Update the status database.
-   * This involves copying each field across from the `available'
-   * to the `installed' half of the pkg structure.
+  /*
+   * Update the status database.
+   *
+   * This involves copying each field across from the ‘available’
+   * to the ‘installed’ half of the pkg structure.
    * For some of the fields we have to do a complicated construction
    * operation; for others we can just copy the value.
    * We tackle the fields in the order they appear, so that
@@ -946,11 +954,10 @@ void process_archive(const char *filename) {
    * to, because these are never modified and never freed.
    */
 
-  /* The dependencies are the most difficult.  We have to build
-   * a whole new forward dependency tree.  At least the reverse
+  /* The dependencies are the most difficult. We have to build
+   * a whole new forward dependency tree. At least the reverse
    * links (linking our deppossi's into the reverse chains)
-   * can be done by copy_dependency_links.
-   */
+   * can be done by copy_dependency_links. */
   newdeplist = NULL;
   newdeplistlastp = &newdeplist;
   for (dep= pkg->available.depends; dep; dep= dep->next) {
@@ -981,16 +988,14 @@ void process_archive(const char *filename) {
   /* Right, now we've replicated the forward tree, we
    * get copy_dependency_links to remove all the old dependency
    * structures from the reverse links and add the new dependency
-   * structures in instead.  It also copies the new dependency
-   * structure pointer for this package into the right field.
-   */
+   * structures in instead. It also copies the new dependency
+   * structure pointer for this package into the right field. */
   copy_dependency_links(pkg,&pkg->installed.depends,newdeplist,0);
 
-  /* The `depended' pointer in the structure doesn't represent anything
+  /* The ‘depended’ pointer in the structure doesn't represent anything
    * that is actually specified by this package - it's there so we
-   * can find out what other packages refer to this one.  So,
-   * we don't copy it.  We go straight on to copy the text fields.
-   */
+   * can find out what other packages refer to this one. So,
+   * we don't copy it. We go straight on to copy the text fields. */
   pkg->installed.essential= pkg->available.essential;
   pkg->installed.description= pkg->available.description;
   pkg->installed.maintainer= pkg->available.maintainer;
@@ -1015,8 +1020,7 @@ void process_archive(const char *filename) {
   }
 
   /* We can just copy the arbitrary fields list, because it is
-   * never even rearranged. Phew!
-   */
+   * never even rearranged. Phew! */
   pkg->installed.arbs= pkg->available.arbs;
 
   /* Check for disappearing packages:
@@ -1024,11 +1028,10 @@ void process_archive(const char *filename) {
    * whose files are entirely part of the one we've just unpacked
    * (and which actually *have* some files!).
    *
-   * Any that we find are removed - we run the postrm with `disappear'
+   * Any that we find are removed - we run the postrm with ‘disappear’
    * as an argument, and remove their info/... files and status info.
    * Conffiles are ignored (the new package had better do something
-   * with them !).
-   */
+   * with them!). */
   it = pkg_db_iter_new();
   while ((otherpkg = pkg_db_iter_next(it)) != NULL) {
     ensure_package_clientdata(otherpkg);
@@ -1095,10 +1098,9 @@ void process_archive(const char *filename) {
            otherpkg->name);
     log_action("disappear", otherpkg);
     debug(dbg_general, "process_archive disappearing %s",otherpkg->name);
-    /* No, we're disappearing it.  This is the wrong time to go and
-     * run maintainer scripts and things, as we can't back out.  But
-     * what can we do ?  It has to be run this late.
-     */
+    /* No, we're disappearing it. This is the wrong time to go and
+     * run maintainer scripts and things, as we can't back out. But
+     * what can we do ?  It has to be run this late. */
     trig_activate_packageprocessing(otherpkg);
     maintainer_script_installed(otherpkg, POSTRMFILE,
                                 "post-removal script (for disappearance)",
@@ -1107,7 +1109,7 @@ void process_archive(const char *filename) {
                                                 vdew_nonambig),
                                 NULL);
 
-    /* OK, now we delete all the stuff in the `info' directory .. */
+    /* OK, now we delete all the stuff in the ‘info’ directory .. */
     varbufreset(&fnvb);
     varbufaddstr(&fnvb, pkgadmindir());
     infodirbaseused= fnvb.used;
@@ -1155,10 +1157,9 @@ void process_archive(const char *filename) {
    * We have to do this before we claim this package is in any
    * sane kind of state, as otherwise we might delete by mistake
    * a file that we overwrote, when we remove the package which
-   * had the version we overwrote.  To prevent this we make
+   * had the version we overwrote. To prevent this we make
    * sure that we don't claim this package is OK until we
-   * have claimed `ownership' of all its files.
-   */
+   * have claimed ‘ownership’ of all its files. */
   for (cfile= newfileslist; cfile; cfile= cfile->next) {
     struct filepackages_iterator *iter;
 
@@ -1205,8 +1206,7 @@ void process_archive(const char *filename) {
   /* Right, the package we've unpacked is now in a reasonable state.
    * The only thing that we have left to do with it is remove
    * backup files, and we can leave the user to fix that if and when
-   * it happens (we leave the reinstall required flag, of course).
-   */
+   * it happens (we leave the reinstall required flag, of course). */
   pkg->status= stat_unpacked;
   modstatdb_note(pkg);
   
@@ -1218,8 +1218,7 @@ void process_archive(const char *filename) {
    * Note that we don't ever delete things that were in the old
    * package as a conffile and don't appear at all in the new.
    * They stay recorded as obsolete conffiles and will eventually
-   * (if not taken over by another package) be forgotten.
-   */
+   * (if not taken over by another package) be forgotten. */
   for (cfile= newfileslist; cfile; cfile= cfile->next) {
     if (cfile->namenode->flags & fnnf_new_conff) continue;
     varbuf_trunc(&fnametmpvb, fnameidlu);
@@ -1230,8 +1229,7 @@ void process_archive(const char *filename) {
   }
 
   /* OK, we're now fully done with the main package.
-   * This is quite a nice state, so we don't unwind past here.
-   */
+   * This is quite a nice state, so we don't unwind past here. */
   pkg->eflag = eflag_ok;
   modstatdb_note(pkg);
   push_checkpoint(~ehflag_bombout, ehflag_normaltidy);
@@ -1239,10 +1237,10 @@ void process_archive(const char *filename) {
   /* Only the removal of the conflictor left to do.
    * The files list for the conflictor is still a little inconsistent in-core,
    * as we have not yet updated the filename->packages mappings; however,
-   * the package->filenames mapping is 
-   */
+   * the package->filenames mapping is. */
   for (i = 0 ; i < cflict_index ; i++) {
-    /* We need to have the most up-to-date info about which files are what ... */
+    /* We need to have the most up-to-date info about which files are
+     * what ... */
     ensure_allinstfiles_available();
     removal_bulk(conflictor[i]);
   }

src/querycmd.c

@@ -99,11 +99,17 @@ list1package(struct pkginfo *pkg, bool *head, struct pkg_array *array)
       }
     } else {
       w-=80;
-      if (w<0) w=0;		/* lets not try to deal with terminals that are too small */
-      w>>=2;		/* halve that so we can add that to the both the name and description */
-      nw=(14+w);		/* name width */
-      vw=(14+w);		/* version width */
-      dw=(44+(2*w));	/* description width */
+      /* Let's not try to deal with terminals that are too small. */
+      if (w < 0)
+        w = 0;
+      /* Halve that so we can add it to both the name and description. */
+      w >>= 2;
+      /* Name width. */
+      nw = (14 + w);
+      /* Version width. */
+      vw = (14 + w);
+      /* Description width. */
+      dw = (44 + (2 * w));
     }
     sprintf(format,"%%c%%c%%c %%-%d.%ds %%-%d.%ds %%.*s\n", nw, nw, vw, vw);
   }
@@ -120,10 +126,23 @@ Desired=Unknown/Install/Remove/Purge/Hold\n\
 | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend\n\
 |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)\n"), stdout);
     printf(format,'|','|','/', _("Name"), _("Version"), 40, _("Description"));
-    printf("+++-");					/* status */
-    for (l=0;l<nw;l++) printf("="); printf("-");	/* packagename */
-    for (l=0;l<vw;l++) printf("="); printf("-");	/* version */
-    for (l=0;l<dw;l++) printf("="); 			/* description */
+
+    /* Status */
+    printf("+++-");
+
+   /* Package name. */
+    for (l = 0; l < nw; l++)
+      printf("=");
+    printf("-");
+
+    /* Version. */
+    for (l = 0; l < vw; l++)
+      printf("=");
+    printf("-");
+
+    /* Description. */
+    for (l = 0; l < dw; l++)
+      printf("=");
     printf("\n");
     *head = true;
   }
@@ -256,9 +275,8 @@ searchfiles(const char *const *argv)
   while ((thisarg = *argv++) != NULL) {
     found= 0;
 
-    /* Trim trailing slash and slash dot from the argument if it's
-     * not a pattern, just a path.
-     */
+    /* Trim trailing ‘/’ and ‘/.’ from the argument if it's
+     * not a pattern, just a path. */
     if (!strpbrk(thisarg, "*[?\\")) {
       varbufreset(&path);
       varbufaddstr(&path, thisarg);
@@ -651,11 +669,10 @@ const char printforhelp[]= N_("Use --help for help about querying packages.");
 
 const char *admindir= ADMINDIR;
 
+/* This table has both the action entries in it and the normal options.
+ * The action entries are made with the ACTION macro, as they all
+ * have a very similar structure. */
 static const struct cmdinfo cmdinfos[]= {
-  /* This table has both the action entries in it and the normal options.
-   * The action entries are made with the ACTION macro, as they all
-   * have a very similar structure.
-   */
   ACTION( "listfiles",                      'L', act_listfiles,     enqperpackage   ),
   ACTION( "status",                         's', act_status,        enqperpackage   ),
   ACTION( "print-avail",                    'p', act_printavail,    enqperpackage   ),

src/remove.c

@@ -43,8 +43,11 @@
 #include "filesdb.h"
 #include "main.h"
 
+/*
+ * pkgdepcheck may be a virtual pkg.
+ */
 static void checkforremoval(struct pkginfo *pkgtoremove,
-                            struct pkginfo *pkgdepcheck, /* may be virtual pkg */
+                            struct pkginfo *pkgdepcheck,
                             int *rokp, struct varbuf *raemsgs) {
   struct deppossi *possi;
   struct pkginfo *depender;
@@ -164,7 +167,8 @@ void deferred_remove(struct pkginfo *pkg) {
     maintainer_script_installed(pkg, PRERMFILE, "pre-removal",
                                 "remove", NULL);
 
-    pkg->status= stat_unpacked; /* Will turn into halfinstalled soon ... */
+    /* Will turn into ‘half-installed’ soon ... */
+    pkg->status = stat_unpacked;
   }
 
   removal_bulk(pkg);
@@ -234,9 +238,8 @@ static void removal_bulk_remove_files(
       if (!stat(fnvb.buf,&stab) && S_ISDIR(stab.st_mode)) {
         debug(dbg_eachfiledetail, "removal_bulk is a directory");
         /* Only delete a directory or a link to one if we're the only
-         * package which uses it.  Other files should only be listed
-         * in this package (but we don't check).
-         */
+         * package which uses it. Other files should only be listed
+         * in this package (but we don't check). */
 	if (hasdirectoryconffiles(namenode,pkg)) {
 	  push_leftover(&leftover,namenode);
 	  continue;
@@ -343,9 +346,8 @@ static void removal_bulk_remove_leftover_dirs(struct pkginfo *pkg) {
     if (!stat(fnvb.buf,&stab) && S_ISDIR(stab.st_mode)) {
       debug(dbg_eachfiledetail, "removal_bulk is a directory");
       /* Only delete a directory or a link to one if we're the only
-       * package which uses it.  Other files should only be listed
-       * in this package (but we don't check).
-       */
+       * package which uses it. Other files should only be listed
+       * in this package (but we don't check). */
       if (hasdirectoryconffiles(namenode,pkg)) {
 	push_leftover(&leftover,namenode);
 	continue;
@@ -393,18 +395,18 @@ static void removal_bulk_remove_configfiles(struct pkginfo *pkg) {
     printf(_("Purging configuration files for %s ...\n"),pkg->name);
     log_action("purge", pkg);
     trig_activate_packageprocessing(pkg);
-    ensure_packagefiles_available(pkg); /* We may have modified this above. */
+
+    /* We may have modified this above. */
+    ensure_packagefiles_available(pkg);
 
     /* We're about to remove the configuration, so remove the note
-     * about which version it was ...
-     */
+     * about which version it was ... */
     blankversion(&pkg->configversion);
     modstatdb_note(pkg);
     
     /* Remove from our list any conffiles that aren't ours any more or
      * are involved in diversions, except if we are the package doing the
-     * diverting.
-     */
+     * diverting. */
     for (lconffp = &pkg->installed.conffiles; (conff = *lconffp) != NULL; ) {
       for (searchfile= pkg->clientdata->files;
            searchfile && strcmp(searchfile->namenode->name,conff->name);
@@ -504,12 +506,12 @@ static void removal_bulk_remove_configfiles(struct pkginfo *pkg) {
                                 "purge", NULL);
 }
 
+/*
+ * This is used both by deferred_remove() in this file, and at the end of
+ * process_archive() in archives.c if it needs to finish removing a
+ * conflicting package.
+ */
 void removal_bulk(struct pkginfo *pkg) {
-  /* This is used both by deferred_remove in this file, and at
-   * the end of process_archive in archives.c if it needs to finish
-   * removing a conflicting package.
-   */
-
   int pkgnameused;
   bool foundpostrm = false;
   const char *postrmfilename;
@@ -536,8 +538,7 @@ void removal_bulk(struct pkginfo *pkg) {
   
   if (!foundpostrm && !pkg->installed.conffiles) {
     /* If there are no config files and no postrm script then we
-     * go straight into `purge'.
-     */
+     * go straight into ‘purge’.  */
     debug(dbg_general, "removal_bulk no postrm, no conffiles, purging");
     pkg->want= want_purge;
 
@@ -548,11 +549,11 @@ void removal_bulk(struct pkginfo *pkg) {
 
   }
 
+  /* I.e., either of the two branches above. */
   if (pkg->want == want_purge) {
-    /* ie, either of the two branches above. */
     static struct varbuf fnvb;
 
-    /* retry empty directories, and warn on any leftovers that aren't */
+    /* Retry empty directories, and warn on any leftovers that aren't. */
     removal_bulk_remove_leftover_dirs(pkg);
 
     varbufreset(&fnvb);
@@ -575,8 +576,7 @@ void removal_bulk(struct pkginfo *pkg) {
     pkg->want = want_unknown;
 
     /* This will mess up reverse links, but if we follow them
-     * we won't go back because pkg->status is stat_notinstalled.
-     */
+     * we won't go back because pkg->status is stat_notinstalled. */
     pkg_perfile_blank(&pkg->installed);
   }
       

src/trigproc.c

@@ -41,50 +41,49 @@
  * Trigger processing algorithms:
  *
  *
- * There is a separate queue (`deferred trigproc list') for triggers
- * `relevant' to what we just did; when we find something triggered `now'
+ * There is a separate queue (‘deferred trigproc list’) for triggers
+ * ‘relevant’ to what we just did; when we find something triggered ‘now’
  * we add it to that queue (unless --no-triggers).
  *
  *
  * We want to prefer configuring packages where possible to doing
  * trigger processing, but we want to prefer trigger processing to
- * cycle-breaking and dependency forcing.  This is achieved as
+ * cycle-breaking and dependency forcing. This is achieved as
  * follows:
  *
  * Each time during configure processing where a package D is blocked by
  * only (ie Depends unsatisfied but would be satisfied by) a t-awaiter W
- * we make a note of (one of) W's t-pending, T.  (Only the last such T.)
+ * we make a note of (one of) W's t-pending, T. (Only the last such T.)
  * (If --no-triggers and nonempty argument list and package isn't in
  * argument list then we don't do this.)
  *
  * Each time in packages.c where we increment dependtry, we instead see
- * if we have encountered such a t-pending T.  If we do, we trigproc T
+ * if we have encountered such a t-pending T. If we do, we trigproc T
  * instead of incrementing dependtry and this counts as having done
  * something so we reset sincenothing.
  *
  *
  * For --triggers-only and --configure, we go through each thing in the
  * argument queue (the add_to_queue queue) and check what its state is
- * and if appropriate we trigproc it.  If we didn't have a queue (or had
+ * and if appropriate we trigproc it. If we didn't have a queue (or had
  * just --pending) we search all triggers-pending packages and add them
  * to the deferred trigproc list.
  *
  *
  * Before quitting from most operations, we trigproc each package in the
- * deferred trigproc list.  This may (if not --no-triggers) of course add
+ * deferred trigproc list. This may (if not --no-triggers) of course add
  * new things to the deferred trigproc list.
  *
  *
- * Note that `we trigproc T' must involve trigger cycle detection and
- * also automatic setting of t-awaiters to t-pending or installed.  In
+ * Note that ‘we trigproc T’ must involve trigger cycle detection and
+ * also automatic setting of t-awaiters to t-pending or installed. In
  * particular, we do cycle detection even for trigger processing in the
  * configure dependtry loop (and it is OK to do it for explicitly
  * specified packages from the command line arguments; duplicates are
  * removed by packages.c:process_queue).
- *
  */
 
-/*========== deferred trigger queue ==========*/
+/*========== Deferred trigger queue. ==========*/
 
 static struct pkg_queue deferred = PKG_QUEUE_INIT;
 
@@ -127,6 +126,9 @@ trigproc_run_deferred(void)
 	}
 }
 
+/*
+ * Called by modstatdb_note.
+ */
 void
 trig_activate_packageprocessing(struct pkginfo *pkg)
 {
@@ -137,7 +139,7 @@ trig_activate_packageprocessing(struct pkginfo *pkg)
 	              trig_cicb_statuschange_activate, pkg);
 }
 
-/*========== actual trigger processing ==========*/
+/*========== Actual trigger processing. ==========*/
 
 struct trigcyclenode {
 	struct trigcyclenode *next;
@@ -161,7 +163,9 @@ trigproc_reset_cycle(void)
 	tortoise = hare = NULL;
 }
 
-/* Returns package we're to give up on. */
+/*
+ * Returns package we're to give up on.
+ */
 static struct pkginfo *
 check_trigger_cycle(struct pkginfo *processing_now)
 {
@@ -207,8 +211,7 @@ check_trigger_cycle(struct pkginfo *processing_now)
 	/* Now we compare hare to tortoise.
 	 * We want to find a trigger pending in tortoise which is not in hare
 	 * if we find such a thing we have proved that hare isn't a superset
-	 * of tortoise and so that we haven't found a loop (yet).
-	 */
+	 * of tortoise and so that we haven't found a loop (yet). */
 	for (tortoise_pkg = tortoise->pkgs;
 	     tortoise_pkg;
 	     tortoise_pkg = tortoise_pkg->next) {
@@ -242,7 +245,8 @@ check_trigger_cycle(struct pkginfo *processing_now)
 			found_in_hare:;
 		}
 	}
-	/* Oh dear. hare is a superset of tortoise. We are making no progress. */
+	/* Oh dear. hare is a superset of tortoise. We are making no
+	 * progress. */
 	fprintf(stderr, _("%s: cycle found while processing triggers:\n chain of"
 	        " packages whose triggers are or may be responsible:\n"),
 	        thisname);
@@ -279,6 +283,10 @@ check_trigger_cycle(struct pkginfo *processing_now)
 	return giveup;
 }
 
+/*
+ * Does cycle checking. Doesn't mind if pkg has no triggers pending - in
+ * that case does nothing but fix up any stale awaiters.
+ */
 void
 trigproc(struct pkginfo *pkg)
 {
@@ -311,9 +319,8 @@ trigproc(struct pkginfo *pkg)
 		}
 		varbufaddc(&namesarg, 0);
 
-		/* Setting the status to halfconfigured
-		 * causes modstatdb_note to clear pending triggers.
-		 */
+		/* Setting the status to half-configured
+		 * causes modstatdb_note to clear pending triggers. */
 		pkg->status = stat_halfconfigured;
 		modstatdb_note(pkg);
 
@@ -335,7 +342,7 @@ trigproc(struct pkginfo *pkg)
 	}
 }
 
-/*========== transitional global activation ==========*/
+/*========== Transitional global activation. ==========*/
 
 static void
 transitional_interest_callback_ro(const char *trig, void *user)
@@ -358,13 +365,14 @@ transitional_interest_callback(const char *trig, void *user)
 	transitional_interest_callback_ro(trig, user);
 }
 
+/*
+ * cstatus might be msdbrw_readonly if we're in --no-act mode, in which
+ * case we don't write out all of the interest files etc. but we do
+ * invent all of the activations for our own benefit.
+ */
 static void
 trig_transitional_activate(enum modstatdb_rw cstatus)
 {
-	/* cstatus might be _read if we're in --no-act mode, in which
-	 * case we don't write out all of the interest files etc.
-	 * but we do invent all of the activations for our own benefit.
-	 */
 	struct pkgiterator *it;
 	struct pkginfo *pkg;
 
@@ -388,7 +396,7 @@ trig_transitional_activate(enum modstatdb_rw cstatus)
 	}
 }
 
-/*========== hook setup ==========*/
+/*========== Hook setup. ==========*/
 
 static struct filenamenode *
 th_proper_nn_find(const char *name, bool nonew)

src/update.c

@@ -1,6 +1,6 @@
 /*
  * dpkg - main program for package management
- * update.c - options which update the `available' database
+ * update.c - options which update the ‘available’ database
  *
  * Copyright © 1995 Ian Jackson <ian@chiark.greenend.org.uk>
  *

utils/start-stop-daemon.c

@@ -116,7 +116,7 @@
 #endif
 
 #if defined(OSLinux)
-/* This comes from TASK_COMM_LEN defined in linux's include/linux/sched.h. */
+/* This comes from TASK_COMM_LEN defined in Linux's include/linux/sched.h. */
 #define PROCESS_NAME_SIZE 15
 #endif
 
@@ -193,9 +193,11 @@ struct schedule_item {
 		sched_timeout,
 		sched_signal,
 		sched_goto,
-		sched_forever /* Only seen within parse_schedule and callees */
+		/* Only seen within parse_schedule and callees. */
+		sched_forever,
 	} type;
-	int value; /* Seconds, signal no., or index into array. */
+	/* Seconds, signal no., or index into array. */
+	int value;
 };
 
 static struct res_schedule *proc_sched = NULL;
@@ -808,7 +810,7 @@ parse_options(int argc, char * const *argv)
 			execname = optarg;
 			break;
 		case 'c':  /* --chuid <username>|<uid> */
-			/* we copy the string just in case we need the
+			/* We copy the string just in case we need the
 			 * argument later. */
 			changeuser = xstrdup(optarg);
 			changeuser = strtok(changeuser, ":");
@@ -1070,7 +1072,7 @@ pid_is_cmd(pid_t pid, const char *name)
 		fclose(f);
 		return false;
 	}
-	/* This hopefully handles command names containing ')'. */
+	/* This hopefully handles command names containing ‘)’. */
 	while ((c = getc(f)) != EOF && c == *name)
 		name++;
 	fclose(f);
@@ -1116,8 +1118,8 @@ pid_is_cmd(pid_t pid, const char *name)
 	if (pid_argv_p == NULL)
 		errx(1, "%s", kvm_geterr(kd));
 
-	start_argv_0_p = *pid_argv_p;
 	/* Find and compare string. */
+	start_argv_0_p = *pid_argv_p;
 
 	/* Find end of argv[0] then copy and cut of str there. */
 	end_argv_0_p = strchr(*pid_argv_p, ' ');
@@ -1599,7 +1601,7 @@ main(int argc, char **argv)
 	if (umask_value >= 0)
 		umask(umask_value);
 	if (mpidfile && pidfile != NULL) {
-		/* User wants _us_ to make the pidfile. :) */
+		/* User wants _us_ to make the pidfile. */
 		FILE *pidf = fopen(pidfile, "w");
 		pid_t pidt = getpid();
 		if (pidf == NULL)
@@ -1643,11 +1645,12 @@ main(int argc, char **argv)
 	}
 
 	if (background) {
-		/* Continue background setup. */
 		int i;
 
+		/* Set a default umask for dumb programs. */
 		if (umask_value < 0)
-			umask(022); /* Set a default for dumb programs. */
+			umask(022);
+
 		dup2(devnull_fd, 0); /* stdin */
 		dup2(devnull_fd, 1); /* stdout */
 		dup2(devnull_fd, 2); /* stderr */

utils/update-alternatives.c

@@ -864,7 +864,9 @@ alternative_add_choice(struct alternative *a, struct fileset *fs)
 				prev->next = fs;
 			else
 				a->choices = fs;
-			a->modified = true; /* XXX: be smarter in detecting change? */
+
+			/* XXX: Be smarter in detecting change? */
+			a->modified = true;
 			return;
 		}
 		prev = cur;
@@ -1246,7 +1248,7 @@ alternative_save(struct alternative *a, const char *file)
 			sl = sl_prev ? sl_prev : a->slaves;
 			slave_link_free(sl_rm);
 			if (!sl)
-				break; /* no other slave left */
+				break; /* No other slave left. */
 		}
 	}