From c687f38ed631df8c9c4df52303aa13dfc325a624 Mon Sep 17 00:00:00 2001 From: Sami Kerola Date: Mon, 13 Nov 2017 23:27:12 +0000 Subject: [PATCH] docs: improve doxygen documentation Signed-off-by: Sami Kerola --- src/analyze.c | 9 ++-- src/dhcpd-pools.c | 5 +- src/dhcpd-pools.h | 96 +++++++++++++++++++++------------------ src/getdata.c | 7 +-- src/mustach-dhcpd-pools.c | 21 +++++++-- src/other.c | 16 +++++++ src/output.c | 15 +++++- 7 files changed, 111 insertions(+), 58 deletions(-) diff --git a/src/analyze.c b/src/analyze.c index fb1084e..7d7ac72 100644 --- a/src/analyze.c +++ b/src/analyze.c @@ -55,7 +55,8 @@ void prepare_data(struct conf_t *state) qsort(state->ranges, state->num_ranges, sizeof(struct range_t), &rangecomp); } -/*! \brief Perform counting. Join leases with ranges, and update counters. */ +/*!\brief Perform counting. Join leases with ranges, and update range and + * shared network counters. */ void do_counting(struct conf_t *state) { struct range_t *restrict range_p = state->ranges; @@ -64,13 +65,13 @@ void do_counting(struct conf_t *state) double block_size; /* Walk through ranges */ - for (i = 0; i < state->num_ranges; i++) { + for (i = 0; i < state->num_ranges; i++, range_p++) { while (l != NULL && ipcomp(&range_p->first_ip, &l->ip) < 0) l = l->hh.prev; /* rewind */ if (l == NULL) l = state->leases; for (; l != NULL && ipcomp(&l->ip, &range_p->last_ip) <= 0; l = l->hh.next) { - if (ipcomp(&l->ip, &range_p->first_ip) < 0) + if (unlikely(ipcomp(&l->ip, &range_p->first_ip) < 0)) continue; /* cannot happen? */ /* IP in range */ switch (l->type) { @@ -99,7 +100,5 @@ void do_counting(struct conf_t *state) state->shared_net_root->touched += range_p->touched; state->shared_net_root->backups += range_p->backups; } - /* Next range. */ - range_p++; } } diff --git a/src/dhcpd-pools.c b/src/dhcpd-pools.c index 7934cdc..79afc21 100644 --- a/src/dhcpd-pools.c +++ b/src/dhcpd-pools.c @@ -66,6 +66,9 @@ int (*leasecomp) (const struct leases_t *restrict a, const struct leases_t *rest void (*add_lease) (struct conf_t *state, union ipaddr_t *ip, enum ltype type); struct leases_t *(*find_lease) (struct conf_t *state, union ipaddr_t *ip); +/*! \brief An option argument parser to populate state header_limit and + * number_limit values. + */ static int return_limit(const char c) { if ('0' <= c && c < '8') @@ -129,7 +132,7 @@ static void skip_arg_parse(struct conf_t *state, char *optarg) } } -/*! \brief Command options parser. */ +/*! \brief Command line options parser. */ static char parse_command_line_opts(struct conf_t *state, int argc, char **argv) { enum { diff --git a/src/dhcpd-pools.h b/src/dhcpd-pools.h index 879e5a1..42e6138 100644 --- a/src/dhcpd-pools.h +++ b/src/dhcpd-pools.h @@ -61,7 +61,11 @@ # define unlikely(x) (x) # endif -/* The attribute __hot__ was added in gcc 4.3. */ +/*! \def _DP_ATTRIBUTE_HOT + * \brief The function attribute __hot__ was added in gcc 4.3. See gnu + * documentation for further information. + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-hot-function-attribute + */ # if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3) # define _DP_ATTRIBUTE_HOT __attribute__ ((__hot__)) # else @@ -85,8 +89,9 @@ enum dhcp_version { }; /*! \enum prefix_t - * \brief Enumeration of interesting data in dhcpd.leases file, that has - * to be further examined, and saved. + * \brief Enumeration of interesting data in dhcpd.leases file, that has to + * be further examined, and saved. Functions xstrstr_v4() and xstrstr_v6() + * return one of these values to parse_leases(). */ enum prefix_t { PREFIX_LEASE, @@ -100,15 +105,19 @@ enum prefix_t { NUM_OF_PREFIX }; +/*! \enum color_mode + * \brief Enumeration whether to use or not color output. + */ enum color_mode { color_unknown, color_off, color_on, - color_auto /* default */ + color_auto /*!< Default, use colors when output terminal is interactive. */ }; /*! \struct shared_network_t - * \brief Counters for an individual shared network. + * \brief Counters for an individual shared network. This data entry is + * also used for 'all networks' counting. */ struct shared_network_t { char *name; @@ -145,7 +154,7 @@ struct output_helper_t { }; /*! \enum ltype - * \brief Lease state types. + * \brief Lease state types. These are the possible values in struct leases_t. */ enum ltype { ACTIVE, @@ -154,7 +163,7 @@ enum ltype { }; /*! \struct leases_t - * \brief An individual lease. The leaases are hashed. + * \brief An individual lease. These leaases are hashed. */ struct leases_t { union ipaddr_t ip; /* ip as key */ @@ -164,16 +173,16 @@ struct leases_t { }; /*! \enum limbits - * \brief Output limit bits: R_BIT ranges, S_BIT shared networks, A_BIT all. + * \brief Output limit bits. */ enum limbits { - R_BIT = (1 << 0), - S_BIT = (1 << 1), - A_BIT = (1 << 2) + R_BIT = (1 << 0), /*!< Range limit. */ + S_BIT = (1 << 1), /*!< Shared networks limit. */ + A_BIT = (1 << 2) /*!< All networks summary limit. */ }; /*! \def STATE_OK - * \brief Nagios alarm exit values. + * \brief Nagios alarm exit value. */ # define STATE_OK 0 # define STATE_WARNING 1 @@ -196,39 +205,38 @@ struct output_sort { * \brief Runtime configuration state. */ struct conf_t { - struct shared_network_t *shared_net_root; - struct shared_network_t *shared_net_head; - struct range_t *ranges; - unsigned int num_ranges; - size_t ranges_size; - struct leases_t *leases; - char dhcpv6; - enum dhcp_version ip_version; - const char *dhcpdconf_file; - const char *dhcpdlease_file; - int output_format; - struct output_sort *sorts; - const char *output_file; - const char *mustach_template; - double warning; - double critical; - double warn_count; - double crit_count; - double minsize; + struct shared_network_t *shared_net_root; /*!< First entry in shared network linked list, that is the 'all networks', */ + struct shared_network_t *shared_net_head; /*!< Last entry in shared network linked list. */ + struct range_t *ranges; /*!< Array of ranges. */ + unsigned int num_ranges; /*!< Number of ranges in the ranges array. */ + size_t ranges_size; /*!< Size of the ranges array. */ + struct leases_t *leases; /*!< An array of individual leases from dhcpd.leases file. */ + enum dhcp_version ip_version; /*!< Designator if the dhcpd is running in IPv4 or IPv6 mode. */ + const char *dhcpdconf_file; /*!< Path to dhcpd.conf file. */ + const char *dhcpdlease_file; /*!< Path to dhcpd.leases file. */ + int output_format; /*!< Column to use in color_tags array. */ + struct output_sort *sorts; /*!< Linked list how to sort ranges. */ + const char *output_file; /*!< Output file path. */ + const char *mustach_template; /*!< Mustach template file path. */ + double warning; /*!< Warning percent threshold. */ + double critical; /*!< Critical percent threshold. */ + double warn_count; /*!< Maximum number of free IP's before warning. */ + double crit_count; /*!< Maximum number of free IP's before critical. */ + double minsize; /*!< Minimum size of range or shared network to be considered exceeding threshold. */ unsigned int - reverse_order:1, - backups_found:1, - snet_alarms:1, - perfdata:1, - all_as_shared:1, - header_limit:4, - number_limit:3, - skip_ok:1, - skip_warning:1, - skip_critical:1, - skip_minsize:1, - skip_suppressed:1, - color_mode:2; + reverse_order:1, /*!< Reverse sort order. */ + backups_found:1, /*!< Indicator if dhcpd.leases file has leases in backup state. */ + snet_alarms:1, /*!< Suppress alarming thresholds for ranges that are part of a shared network. */ + perfdata:1, /*!< Include performance statistics when using Nagios alarm output format. */ + all_as_shared:1, /*!< Treat stand-alone subnets as a shared network. */ + header_limit:4, /*!< Bits to suppress header output. */ + number_limit:3, /*!< Bits to suppress value output. */ + skip_ok:1, /*!< Skip none-alarming values from output. */ + skip_warning:1, /*!< Skip warning values from output. */ + skip_critical:1, /*!< Skip critical values from output. */ + skip_minsize:1, /*!< Skip alarming values that are below minsize from output. */ + skip_suppressed:1, /*!< Skip alarming values that are suppressed with --snet-alarms option, or they are shared networks without IP availability. */ + color_mode:2; /*!< Indicator if colors should be used in output. */ }; /* Function prototypes */ diff --git a/src/getdata.c b/src/getdata.c index 850f48e..ca01384 100644 --- a/src/getdata.c +++ b/src/getdata.c @@ -64,7 +64,8 @@ enum dhcpd_magic_numbers { }; /*! \enum isc_conf_parser - * \brief Configuration file parsing state flags. + * \brief Configuration file parsing state flags. The + * is_interesting_config_clause() will return one of these to parse_config(). */ enum isc_conf_parser { ITS_NOTHING_INTERESTING, @@ -195,8 +196,8 @@ static void reorder_last_first(struct range_t *range_p) } /*! \brief The dhcpd.conf file parser. - * FIXME: This spaghetti monster function need to be rewrote at least - * ones. + * FIXME: This spaghetti monster function needs to be rewrote at least + * ones more. */ void parse_config(struct conf_t *state, const int is_include, const char *restrict config_file, struct shared_network_t *restrict shared_p) diff --git a/src/mustach-dhcpd-pools.c b/src/mustach-dhcpd-pools.c index 652db0a..67260fd 100644 --- a/src/mustach-dhcpd-pools.c +++ b/src/mustach-dhcpd-pools.c @@ -53,6 +53,9 @@ #include "mustach.h" #include "xalloc.h" +/*! \struct expl + * \brief A structure that travels through mustach via closure void pointer. + */ struct expl { struct conf_t *state; struct range_t *range_p; @@ -64,7 +67,9 @@ struct expl { static int must_enter(void *closure, const char *name); static int must_leave(void *closure); -/* This can be called when template is invalid end put happens before enter. */ +/*! \brief This function can be called when mustach template is invalid. + * In such case either must_put_range or must_put_shnet is tried to call before + * must_enter. */ static int must_put_err(void *closure __attribute__ ((unused)), const char *name __attribute__ ((unused)), int escape __attribute__ ((unused)), FILE *file __attribute__ ((unused))) @@ -72,7 +77,8 @@ static int must_put_err(void *closure __attribute__ ((unused)), return MUSTACH_ERROR_SYSTEM; } -/* Set mustach function pointers. */ +/*! \struct mustach_itf + * \brief Mustach function pointers. */ static struct mustach_itf itf = { .start = NULL, .enter = must_enter, @@ -81,6 +87,7 @@ static struct mustach_itf itf = { .leave = must_leave }; +/*! \brief Mustach range aka {{#subnets}} tag parser and printer. */ static int must_put_range(void *closure, const char *name, int escape __attribute__ ((unused)), FILE *file) { @@ -162,6 +169,7 @@ static int must_put_range(void *closure, const char *name, int escape return 0; } +/*! \brief Mustach shared networks aka {{#shared-networks}} tag parser and printer. */ static int must_put_shnet(void *closure, const char *name, int escape __attribute__ ((unused)), FILE *file) { @@ -230,6 +238,7 @@ static int must_put_shnet(void *closure, const char *name, int escape return 0; } +/*! \brief A function to move to next range when {{/subnets}} is encountered. */ static int must_next_range(void *closure) { struct expl *e = closure; @@ -243,6 +252,8 @@ static int must_next_range(void *closure) return 1; } +/*! \brief A function to move to next shared network when {{/shared-networks}} + * is encountered. */ static int must_next_shnet(void *closure) { struct expl *e = closure; @@ -261,6 +272,8 @@ static int must_next_shnet(void *closure) return 0; } +/*! \brief Function that is called when mustach is searching output loops from + * template file. */ static int must_enter(void *closure, const char *name) { struct expl *e = closure; @@ -292,6 +305,7 @@ static int must_enter(void *closure, const char *name) return 0; } +/*! \brief Function that is called when all elements within a print loop are outputed. */ static int must_leave(void *closure __attribute__ ((unused))) { struct expl *e = closure; @@ -301,6 +315,7 @@ static int must_leave(void *closure __attribute__ ((unused))) return 0; } +/*! \brief Read mustach template to memory. */ static char *must_read_template(const char *filename) { int f; @@ -322,7 +337,7 @@ static char *must_read_template(const char *filename) return result; } - +/*! \brief Start mustach processing. */ int mustach_dhcpd_pools(struct conf_t *state) { struct expl e = { .state = state }; diff --git a/src/other.c b/src/other.c index 8ebe627..dc207bd 100644 --- a/src/other.c +++ b/src/other.c @@ -159,6 +159,10 @@ int parse_ipaddr_v6(struct conf_t *state return rv == 1; } +/*! \brief Convert string to a desimal format network marks. + * \param src Digit that should be a network mask. + * \return Network mask, or -1 when failing. + */ static int strtol_mask(const char *str) { long num; @@ -178,6 +182,10 @@ static int strtol_mask(const char *str) return -1; } +/*! \brief Find last address in IPv4 range by using cidr format. + * \param addr Pointer to memory where address needs to be stored. + * \return Allocated string format of the address. + */ static char *cidr_last_v4(union ipaddr_t *restrict addr, const int mask) { union ipaddr_t last_ip; @@ -194,6 +202,10 @@ static char *cidr_last_v4(union ipaddr_t *restrict addr, const int mask) return xstrdup(ip); } +/*! \brief Find last address in IPv6 range by using cidr format. + * \param addr Pointer to memory where address needs to be stored. + * \return Allocated string format of the address. + */ static char *cidr_last_v6(union ipaddr_t *restrict addr, const int mask) { union ipaddr_t bitmask; @@ -213,6 +225,10 @@ static char *cidr_last_v6(union ipaddr_t *restrict addr, const int mask) return xstrdup(ip); } +/*! \brief Convert a cidr notated address to a range. + * \param range_p Pointer to memory where addresses need to be stored. + * \param word A range as a cidr string. + */ void parse_cidr(struct conf_t *state, struct range_t *range_p, const char *word) { char *divider; diff --git a/src/output.c b/src/output.c index 9052854..9647f0c 100644 --- a/src/output.c +++ b/src/output.c @@ -81,6 +81,9 @@ enum count_status_t { COLOR_RESET }; +/*! \var color_tags + * \brief Array of stings that make colors to start and end in different + * schemas per array column. */ static const char *color_tags[][NUM_OF_OUT_FORMS] = { [STATUS_OK] = { "", "" }, [STATUS_WARN] = { "\033[1;33m", " style=\"color:magenta;font-style:italic\"" }, @@ -90,7 +93,8 @@ static const char *color_tags[][NUM_OF_OUT_FORMS] = { [COLOR_RESET] = { "\033[0m", "" } }; -/*! \brief Calculate range percentages and such. */ +/*! \brief Calculate range percentages and such. + * \return Indicator if the entry should be skipped from output. */ int range_output_helper(struct conf_t *state, struct output_helper_t *oh, struct range_t *range_p) { @@ -127,7 +131,8 @@ int range_output_helper(struct conf_t *state, struct output_helper_t *oh, return 0; } -/*! \brief Calculate shared network percentages and such. */ +/*! \brief Calculate shared network percentages and such. + * \return Indicator if the entry should be skipped from output. */ int shnet_output_helper(struct conf_t *state, struct output_helper_t *oh, struct shared_network_t *shared_p) { @@ -170,6 +175,8 @@ int shnet_output_helper(struct conf_t *state, struct output_helper_t *oh, } +/*! \brief Output a color based on output_helper_t status. + * \return Indicator whether coloring was started or not. */ static int start_color(struct conf_t *state, struct output_helper_t *oh, FILE *outfile) { if (oh->status == STATUS_OK) { @@ -179,6 +186,8 @@ static int start_color(struct conf_t *state, struct output_helper_t *oh, FILE *o return 1; } +/*! \brief Helper function to open a output file. + * \return The outfile in all of the output functions. */ static FILE *open_outfile(struct conf_t *state) { FILE *outfile; @@ -194,6 +203,8 @@ static FILE *open_outfile(struct conf_t *state) return outfile; } + +/*! \brief Helper function to close outfile. */ static void close_outfile(FILE *outfile) { if (outfile == stdout) {