Mark enum and struct member comments as doxygen descriptions

dpkg-split/dpkg-split.h

@@ -40,7 +40,7 @@ struct partinfo {
   off_t maxpartlen;
   off_t thispartoffset;
   off_t thispartlen;
-  /* Size of header in part file. */
+  /** Size of header in part file. */
   off_t headerlen;
   off_t filesize;
 };
@@ -48,7 +48,7 @@ struct partinfo {
 struct partqueue {
   struct partqueue *nextinqueue;
 
-  /* Only fields filename, md5sum, maxpartlen, thispartn, maxpartn
+  /** 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;

lib/dpkg/dpkg-db.h

@@ -109,7 +109,7 @@ struct filedetails {
  */
 struct pkgbin {
   struct dependency *depends;
-  /* The ‘essential’ flag, true = yes, false = no (absent). */
+  /** The ‘essential’ flag, true = yes, false = no (absent). */
   bool essential;
   enum pkgmultiarch {
     multiarch_no,
@@ -118,7 +118,7 @@ struct pkgbin {
     multiarch_foreign,
   } multiarch;
   const struct dpkg_arch *arch;
-  /* The following is the "pkgname:archqual" cached string, if this was a
+  /** The following is the "pkgname:archqual" cached string, if this was a
    * C++ class this member would be mutable. */
   const char *pkgname_archqual;
   const char *description;
@@ -171,10 +171,10 @@ struct pkginfo {
 
   enum pkgwant {
     want_unknown, want_install, want_hold, want_deinstall, want_purge,
-    /* 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. */
+  /** The error flag bitmask. */
   enum pkgeflag {
     eflag_ok		= 0,
     eflag_reinstreq	= 1,
@@ -293,24 +293,25 @@ void pkg_db_report(FILE *);
 /*** from parse.c ***/
 
 enum parsedbflags {
-  /* Store in ‘available’ in-core structures, not ‘status’. */
+  /** Store in ‘available’ in-core structures, not ‘status’. */
   pdb_recordavailable = 001,
-  /* Throw up an error if ‘Status’ encountered. */
+  /** Throw up an error if ‘Status’ encountered. */
   pdb_rejectstatus = 002,
-  /* Ignore priority/section info if we already have any. */
+  /** Ignore priority/section info if we already have any. */
   pdb_weakclassification = 004,
-  /* Ignore files info if we already have them. */
+  /** Ignore files info if we already have them. */
   pdb_ignorefiles = 010,
-  /* Ignore packages with older versions already read. */
+  /** Ignore packages with older versions already read. */
   pdb_ignoreolder = 020,
-  /* Perform laxer version parsing. */
+  /** Perform laxer version parsing. */
   pdb_lax_version_parser = 040,
-  /* Perform laxer parsing, used to transition to stricter parsing. */
+  /** Perform laxer parsing, used to transition to stricter parsing. */
   pdb_lax_parser = pdb_lax_version_parser,
-  /* Parse the control file from a binary .deb package. */
+  /** Parse the control file from a binary .deb package. */
   pdb_deb_control = 0100,
 
   /* Standard operations. */
+
   pdb_parse_status = pdb_lax_parser | pdb_weakclassification,
   pdb_parse_update = pdb_parse_status | pdb_deb_control,
   pdb_parse_available = pdb_recordavailable | pdb_rejectstatus | pdb_lax_parser,
@@ -346,13 +347,13 @@ const char *versiondescribe(const struct versionrevision*,
                             enum versiondisplayepochwhen);
 
 enum pkg_name_arch_when {
-  /* Never display arch. */
+  /** Never display arch. */
   pnaw_never,
-  /* Display arch only when it's non-ambiguous. */
+  /** Display arch only when it's non-ambiguous. */
   pnaw_nonambig,
-  /* Display arch only when it's a foreign one. */
+  /** Display arch only when it's a foreign one. */
   pnaw_foreign,
-  /* Always display arch. */
+  /** Always display arch. */
   pnaw_always,
 };
 
@@ -369,9 +370,9 @@ void writerecord(FILE*, const char*,
                  const struct pkginfo *, const struct pkgbin *);
 
 enum writedb_flags {
-  /* Dump ‘available’ in-core structures, not ‘status’. */
+  /** Dump ‘available’ in-core structures, not ‘status’. */
   wdb_dump_available = 001,
-  /* Must sync the written file. */
+  /** Must sync the written file. */
   wdb_must_sync = 002,
 };
 

lib/dpkg/parsedump.h

@@ -87,7 +87,7 @@ freadfunction f_architecture;
 freadfunction f_trigpend, f_trigaw;
 
 enum fwriteflags {
-	/* Print field header and trailing newline. */
+	/** Print field header and trailing newline. */
 	fw_printheader = 001,
 };
 

lib/dpkg/pkg-spec.h

@@ -37,7 +37,7 @@ struct pkg_spec {
 	const struct dpkg_arch *arch;
 
 	enum pkg_spec_flags {
-		/* Recognize glob patterns. */
+		/** Recognize glob patterns. */
 		psf_patterns = 00001,
 
 		/* How to consider the lack of an arch qualifier. */
@@ -51,9 +51,9 @@ struct pkg_spec {
 	bool name_is_pattern;
 	bool arch_is_pattern;
 
-	/* Used for the pkg_db iterator. */
+	/** Used for the pkg_db iterator. */
 	struct pkgiterator *pkg_iter;
-	/* Used for the pkgset iterator. */
+	/** Used for the pkgset iterator. */
 	struct pkginfo *pkg_next;
 };
 

lib/dpkg/tarfn.h

@@ -39,7 +39,8 @@ enum tar_format {
 };
 
 enum tar_filetype {
-	tar_filetype_file0 = '\0',	/* For compatibility with decades-old bug */
+	/** For compatibility with decades-old bug. */
+	tar_filetype_file0 = '\0',
 	tar_filetype_file = '0',
 	tar_filetype_hardlink = '1',
 	tar_filetype_symlink = '2',
@@ -52,13 +53,20 @@ enum tar_filetype {
 };
 
 struct tar_entry {
-	enum tar_format format;	/* Tar archive format. */
-	enum tar_filetype type;	/* Regular, Directory, Special, Link */
-	char *name;		/* File name */
-	char *linkname;		/* Name for symbolic and hard links */
-	off_t size;		/* Size of file */
-	time_t mtime;		/* Last-modified time. */
-	dev_t dev;		/* Special device for mknod() */
+	/** Tar archive format. */
+	enum tar_format format;
+	/** File type. */
+	enum tar_filetype type;
+	/** File name. */
+	char *name;
+	/** Symlink or hardlink name. */
+	char *linkname;
+	/** File size. */
+	off_t size;
+	/** Last-modified time. */
+	time_t mtime;
+	/** Special device for mknod(). */
+	dev_t dev;
 
 	struct file_stat stat;
 };

lib/dpkg/trigdeferred.h

@@ -30,7 +30,7 @@ enum trigdef_updateflags {
 	tduf_nolockok =           001,
 	tduf_write =              002,
 	tduf_nolock =             003,
-	/* Should not be set unless _write is. */
+	/** Should not be set unless _write is. */
 	tduf_writeifempty =       010,
 	tduf_writeifenoent =      020,
 };

lib/dpkg/triglib.h

@@ -54,9 +54,11 @@ struct trigfileint {
 	} inoverall;
 };
 
-/* The first two hooks are normally NULL.
+/**
+ * The first two hooks are normally NULL.
  * If non-NULL, we're dpkg proper and we might need to invent trigger
- * activations as the first run of a triggers-supporting dpkg. */
+ * activations as the first run of a triggers-supporting dpkg.
+ */
 struct trig_hooks {
 	void (*enqueue_deferred)(struct pkginfo *pend);
 	void (*transitional_activate)(enum modstatdb_rw cstatus);
@@ -64,7 +66,7 @@ struct trig_hooks {
 	struct filenamenode *(*namenode_find)(const char *filename, bool nonew);
 	struct trigfileint **(*namenode_interested)(struct filenamenode *fnn);
 
-	/* Returns a pointer from nfmalloc. */
+	/** Returns a pointer from nfmalloc. */
 	const char *(*namenode_name)(struct filenamenode *fnn);
 };
 

lib/dpkg/varbuf.h

@@ -29,7 +29,7 @@
 
 DPKG_BEGIN_DECLS
 
-/*
+/**
  * varbuf_init must be called exactly once before the use of each varbuf
  * (including before any call to varbuf_destroy), or the variable must be
  * initialized with VARBUF_INIT.

src/archives.h

@@ -29,7 +29,7 @@ struct tarcontext {
   int backendpipe;
   struct pkginfo *pkg;
   struct fileinlist **newfilesp;
-  /* Are all “Multi-arch: same” instances about to be in sync? */
+  /** Are all “Multi-arch: same” instances about to be in sync? */
   bool pkgset_getting_in_sync;
 };
 

src/filesdb.h

@@ -46,11 +46,13 @@
 
 struct pkginfo;
 
-/* Flags to findnamenode(). */
+/**
+ * Flags to findnamenode().
+ */
 enum fnnflags {
-    /* Do not need to copy filename. */
+    /** Do not need to copy filename. */
     fnn_nocopy = 000001,
-    /* findnamenode may return NULL. */
+    /** findnamenode may return NULL. */
     fnn_nonew = 000002,
 };
 
@@ -60,7 +62,7 @@ struct filenamenode {
   struct filepackages *packages;
   struct diversion *divert;
 
-  /* We allow the administrator to override the owner, group and mode of
+  /** We allow the administrator to override the owner, group and mode of
    * a file. If such an override is present we use that instead of the
    * stat information stored in the archive.
    *
@@ -72,32 +74,32 @@ struct filenamenode {
    * filesdbinit.
    */
 
-  /* Set to zero when a new node is created. */
+  /** Set to zero when a new node is created. */
   enum {
-    /* In the newconffiles list. */
+    /** In the newconffiles list. */
     fnnf_new_conff = 000001,
-    /* In the new filesystem archive. */
+    /** In the new filesystem archive. */
     fnnf_new_inarchive = 000002,
-    /* In the old package's conffiles list. */
+    /** In the old package's conffiles list. */
     fnnf_old_conff = 000004,
-    /* Obsolete conffile. */
+    /** Obsolete conffile. */
     fnnf_obs_conff = 000100,
-    /* Must remove from other packages' lists. */
+    /** Must remove from other packages' lists. */
     fnnf_elide_other_lists = 000010,
-    /* >= 1 instance is a dir, cannot rename over. */
+    /** >= 1 instance is a dir, cannot rename over. */
     fnnf_no_atomic_overwrite = 000020,
-    /* New file has been placed on the disk. */
+    /** New file has been placed on the disk. */
     fnnf_placed_on_disk = 000040,
     fnnf_deferred_fsync = 000200,
     fnnf_deferred_rename = 000400,
-    /* Path being filtered. */
+    /** Path being filtered. */
     fnnf_filtered = 001000,
   } flags;
 
-  /* Valid iff this namenode is in the newconffiles list. */
+  /** Valid iff this namenode is in the newconffiles list. */
   const char *oldhash;
 
-  /* Valid iff the file was unpacked and hashed on this run. */
+  /** Valid iff the file was unpacked and hashed on this run. */
   const char *newhash;
 
   struct stat *filestat;
@@ -109,7 +111,7 @@ 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
@@ -131,7 +133,7 @@ struct diversion {
   struct filenamenode *camefrom;
   struct pkgset *pkgset;
 
-  /* The ‘contested’ halves are in this list for easy cleanup. */
+  /** The ‘contested’ halves are in this list for easy cleanup. */
   struct diversion *next;
 };
 

src/main.h

@@ -33,14 +33,14 @@ struct perpackagestate {
     itb_normal, itb_remove, itb_installnew, itb_deconfigure, itb_preinstall
   } istobe;
 
-  /* Used during cycle detection. */
+  /** Used during cycle detection. */
   enum {
     white,
     gray,
     black,
   } color;
 
-  /*
+  /**
    * filelistvalid  files  Meaning
    * -------------  -----  -------
    * false          NULL   Not read yet, must do so if want them.
@@ -55,7 +55,7 @@ struct perpackagestate {
 
   off_t listfile_phys_offs;
 
-  /* Non-NULL iff in trigproc.c:deferred. */
+  /** Non-NULL iff in trigproc.c:deferred. */
   struct pkg_list *trigprocdeferred;
 };