From 9e41a10fbee567866d78903b11646d341cfd9882 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sun, 2 Nov 2008 22:38:31 +0100 Subject: [PATCH 1/1] Add more source code documentation. --- adu.c | 3 ++- adu.h | 27 ++++++++++++++++++++++ format.c | 25 ++++++++++++++++++++- format.h | 62 +++++++++++++++++++++++++++++++++++++++++++++------ interactive.c | 9 ++++++++ string.c | 2 +- 6 files changed, 118 insertions(+), 10 deletions(-) diff --git a/adu.c b/adu.c index 335cb62..b3ec80e 100644 --- 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 /* readdir() */ #include @@ -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 85ab63a..b9e6ee9 100644 --- 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 bcdbff9..37bb087 100644 --- 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 2b8b7f2..4446f49 100644 --- 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 288e9f3..b325415 100644 --- 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 2825cdc..a219bef 100644 --- 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. * -- 2.39.2