Add more source code documentation.

diff --git a/adu.c b/adu.c
index 335cb62f52f395453464ecc057c96531b1243c08..b3ec80e2377c49e8df37ee2288530212a0e200fa 100644 (file)
--- a/adu.c
+++ b/adu.c
@@ -1,3 +1,4 @@
+/** \file adu.c The main functions used by all modes of operation. */
 #include "adu.h"
 #include <dirent.h> /* readdir() */
 #include <pwd.h>
@@ -178,7 +179,7 @@ static struct osl_column_description user_table_cols[] = {
  * The log function.
  *
  * \param ll Loglevel.
- * \param fml Usual format string.
+ * \param fmt Usual format string.
  *
  * All XXX_LOG() macros use this function.
  */

diff --git a/adu.h b/adu.h
index 85ab63a6e04db918f14f37e3e5f40d9294cb555a..b9e6ee9f67812764c8b65b7baf41bc9d31ef5978 100644 (file)
--- a/adu.h
+++ b/adu.h
@@ -146,6 +146,7 @@ enum user_table_columns {
        NUM_UT_COLUMNS
 };
 
+/** Flags for the user hash table. */
 enum uid_info_flags {
        /** Whether this slot of the hash table is used. */
        UI_FL_SLOT_USED = 1,
@@ -153,19 +154,36 @@ enum uid_info_flags {
        UI_FL_ADMISSIBLE = 2,
 };
 
+/** Information about one admissible user. */
 struct user_info {
+       /** User ID. */
        uint32_t uid;
+       /** \sa enum uid_info_flags. */
        uint32_t flags;
+       /** The user name.  */
        char *pw_name;
+       /** The user table of this user.*/
        struct osl_table *table;
+       /** Total number of files owned by this user. */
        uint64_t files;
+       /** Total number of bytes owned by this user. */
        uint64_t bytes;
+       /** Total number of directories that contain at least one file */
        uint64_t dirs;
+       /** The description of the user table. */
        struct osl_table_description *desc;
 };
 
+/**
+ * Describes one range of admissible user IDs.
+ *
+ * adu converts the admissible user ids given at the command line
+ * into an array of such structs.
+ */
 struct uid_range {
+       /** Lowest admissible user ID. */
        uint32_t low;
+       /** Greatest admissible user ID. */
        uint32_t high;
 };
 
@@ -178,7 +196,16 @@ enum search_uid_flags {
 
 extern uint32_t num_uids;
 extern struct osl_table *dir_table;
+
+/** The adu command line options. */
 extern struct gengetopt_args_info conf;
+
+/**
+ * The select command line options.
+ *
+ * Either given at the command line, or via the \a set command
+ * in interactive mode.
+ */
 extern struct select_args_info select_conf;
 
 /* adu.c */

diff --git a/format.c b/format.c
index bcdbff9ff425df1783975cf8ac62a64ab28fa40e..37bb087ba02fff7f472d14b0739e715626263c26 100644 (file)
--- a/format.c
+++ b/format.c
@@ -13,6 +13,7 @@
 #include "string.h"
 #include "error.h"
 #include "format.h"
+
 enum alignment {ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER};
 
 struct num_format {
@@ -217,6 +218,15 @@ success:
        return 1;
 }
 
+/**
+ * Parse the given string according to the list of given atoms.
+ *
+ * \param fmt The format string.
+ * \param atoms The array of valid atoms.
+ * \param result Points to a format_info structure for later use.
+ *
+ * \return Standard.
+ */
 int parse_format_string(char *fmt, struct atom *atoms, struct format_info **result)
 {
        char *cp, *ap, *ep;
@@ -264,7 +274,12 @@ err:
 }
 
 /**
- * It's OK to pass a \p NULL pointer to this function.
+ * Free a struct of type \a format_info.
+ *
+ * \param info Pointer to the format info to be freed.
+ *
+ * It's OK to pass a \p NULL pointer to this function in which case the
+ * function does nothing.
  */
 void free_format_info(struct format_info *info)
 {
@@ -397,6 +412,14 @@ static char *align_unsigned_int(long long unsigned num, unsigned int width,
                nnum, postfix, width - (width + len) / 2, "");
 }
 
+/**
+ * Pretty-format the given values according to \a info.
+ *
+ * \param info The formating information.
+ * \param values The contents of the atoms.
+ *
+ * \return A string that must be freed by the caller.
+ */
 char *format_items(struct format_info *info, union atom_value *values)
 {
        int i;

diff --git a/format.h b/format.h
index 2b8b7f20e5999c8b27a44a2c9c8c4640ca3ae81b..4446f49c7c7908477dfd6fb546291e0102eadaaf 100644 (file)
--- a/format.h
+++ b/format.h
@@ -1,20 +1,68 @@
-/* format.h */
-enum atom_type {AT_STRING, AT_ID, AT_COUNT, AT_SIZE};
-/*
- * STRING: %(foo:a:w)
- * (U)INT: %(foo:a:w:u)
+/** \file format.h Exported symbols from \p format.c. */
+
+/** The possible types of format string directives (aka atoms). */
+enum atom_type {
+       /** String, supports alignment and width. */
+       AT_STRING,
+       /** Used for user IDs, supports alignment and width. */
+       AT_ID,
+       /**
+        *  Used for number of files/directories, supports alignment,
+        *  width, unit.
+        */
+       AT_COUNT,
+       /**
+        * Used for number of bytes. Like \p AT_COUNT, but the unit is
+        * treated differently: By default, 1024 is used as the base,
+        * and low numbers get a "b" (bytes) appended which does not make
+        * sense for counters.
+        */
+       AT_SIZE
+};
+
+/**
+ * One format string directive.
+ *
+ * Each application must define its own set of valid atoms as an array
+ * of struct atom. The \ref parse_format_string() function takes a format
+ * string and the array of valid atoms and returns an opaque pointer to
+ * a struct \a format_info.
+ *
+ * At a later time the application may pass the \a format_info pointer
+ * together with the current value for each atom to \a format_items() which
+ * returns these values, formated according to the format string which has
+ * been passed to parse_format_string() previously.
+ *
+ * Usually, the application will call parse_format_string() only once, but
+ * format_items() many times.
  */
 struct atom {
+       /** The name of the directive. */
        const char const *name;
+       /** Its type. */
        enum atom_type type;
 };
 
+/**
+ * The current value of one atom.
+ *
+ * An array of this type, whose entries must match the array of valid atoms,
+ * may be passed to format_items() to obtain a formated string.
+ */
 union atom_value {
+       /** Used for atoms of type string. */
        char *string_value;
+       /** Used for atoms not of type string. */
        long long unsigned num_value;
 };
 
-struct format_info; /* opaque */
-int parse_format_string(char *fmt, struct atom *atoms, struct format_info **result);
+/**
+ * The details of this structure are only relevant to the functions in \p
+ * format.c.
+ */
+struct format_info;
+
+int parse_format_string(char *fmt, struct atom *atoms,
+               struct format_info **result);
 char *format_items(struct format_info *info, union atom_value *values);
 void free_format_info(struct format_info *info);

diff --git a/interactive.c b/interactive.c
index 288e9f3031f2890f73282a67ebd04be5bdffe142..b3254157d6785403573252876624c026ed912ed4 100644 (file)
--- a/interactive.c
+++ b/interactive.c
@@ -7,9 +7,18 @@
 #include "error.h"
 #include "cmdline.h"
 
+/**
+ * Describes one valid command for interactive mode.
+ *
+ * When invoked in interactive mode, adu reads commands from stdin. There's a
+ * static array of all such commands.
+ */
 struct interactive_command {
+       /** The name of the command. */
        const char *name;
+       /** Pointer to The function that is being executed. */
        int (*handler)(char *);
+       /** Help text. */
        const char *desc;
 };
 

diff --git a/string.c b/string.c
index 2825cdca798d7366277768c522cfdc62ff5d315a..a219bef6fec4410e2eb44c07713f02778a42cf60 100644 (file)
--- a/string.c
+++ b/string.c
@@ -170,7 +170,7 @@ __must_check __malloc char *adu_strcat(char *a, const char *b)
  * Convert a string to a 64-bit signed integer value.
  *
  * \param str The string to be converted.
- * \param value Result pointer.
+ * \param result Result pointer.
  *
  * \return Standard.
  *