From 6883cb029f7d1d78617f2ffbd73955beaeb4e1a7 Mon Sep 17 00:00:00 2001 From: Michael Poole Date: Wed, 29 Sep 2004 04:29:57 +0000 Subject: [PATCH] Doxyfy ircd_features.h and ircd_features.c. git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1192 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- include/ircd_features.h | 9 +- ircd/ircd_features.c | 189 +++++++++++++++++++++++++++------------- 2 files changed, 137 insertions(+), 61 deletions(-) diff --git a/include/ircd_features.h b/include/ircd_features.h index fcfd02c..4c0e634 100644 --- a/include/ircd_features.h +++ b/include/ircd_features.h @@ -17,13 +17,18 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/* @file + * @brief Public interfaces and declarations for dealing with configurable features. + * @version $Id$ */ struct Client; struct StatDesc; +/** Contains all feature settings for ircu. + * For documentation of each, see doc/readme.features. + */ enum Feature { /* Misc. features */ FEAT_LOG, diff --git a/ircd/ircd_features.c b/ircd/ircd_features.c index 925e8fe..fcf92f1 100644 --- a/ircd/ircd_features.c +++ b/ircd/ircd_features.c @@ -15,8 +15,10 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/* @file + * @brief Implementation of configurable feature support. + * @version $Id$ */ #include "config.h" @@ -48,11 +50,11 @@ #include #include -/* List of log output types that can be set */ +/** List of log output types that can be set */ static struct LogTypes { - char *type; - int (*set)(const char *, const char *); - char *(*get)(const char *); + char *type; /**< Settable name. */ + int (*set)(const char *, const char *); /**< Function to set the value. */ + char *(*get)(const char *); /**< Functino to get the value. */ } logTypes[] = { { "FILE", log_set_file, log_get_file }, { "FACILITY", log_set_facility, log_get_facility }, @@ -61,7 +63,11 @@ static struct LogTypes { { 0, 0, 0 } }; -/* Look up a struct LogType given the type string */ +/** Look up a struct LogType given the type string. + * @param[in] from &Client requesting type, or NULL. + * @param[in] type Name of log type to find. + * @return Pointer to the found LogType, or NULL if none was found. + */ static struct LogTypes * feature_log_desc(struct Client* from, const char *type) { @@ -82,7 +88,12 @@ feature_log_desc(struct Client* from, const char *type) return 0; /* not found */ } -/* Set the value of a log output type for a log subsystem */ +/** Set the value of a log output type for a log subsystem. + * @param[in] from &Client trying to set the log type, or NULL. + * @param[in] fields Array of parameters to set. + * @param[in] count Number of parameters in \a fields. + * @return -1 to clear the mark, 0 to leave the mask alone, 1 to set the mask. + */ static int feature_log_set(struct Client* from, const char* const* fields, int count) { @@ -122,7 +133,12 @@ feature_log_set(struct Client* from, const char* const* fields, int count) return 0; } -/* reset a log type for a subsystem to its default value */ +/** Reset a log type for a subsystem to its default value. + * @param[in] from &Client trying to reset the subsystem. + * @param[in] fields Array of parameters to reset. + * @param[in] count Number of fields in \a fields. + * @return -1 to unmark the entry, or zero to leave it alone. + */ static int feature_log_reset(struct Client* from, const char* const* fields, int count) { @@ -144,7 +160,11 @@ feature_log_reset(struct Client* from, const char* const* fields, int count) return 0; } -/* report the value of a log setting */ +/** Report the value of a log setting. + * @param[in] from &Client asking for details. + * @param[in] fields Array of parameters to get. + * @param[in] count Number of fields in \a fields. + */ static void feature_log_get(struct Client* from, const char* const* fields, int count) { @@ -171,64 +191,83 @@ feature_log_get(struct Client* from, const char* const* fields, int count) } } -/* sets a feature to the given value */ -typedef int (*feat_set_call)(struct Client*, const char* const*, int); -/* gets the value of a feature */ -typedef void (*feat_get_call)(struct Client*, const char* const*, int); -/* callback to notify of a feature's change */ +/** Sets a feature to the given value. + * @param[in] from Client trying to set parameters. + * @param[in] fields Array of paraters to set. + * @param[in] count Number of fields in \a count. + * @return <0 to clear the feature mark, 0 to leave it, >0 to set the feature mark. + */ +typedef int (*feat_set_call)(struct Client* from, const char* const* fields, int count); +/** Gets the value of a feature. + * @param[in] from Client trying to get parameters. + * @param[in] fields Array of paraters to set. + * @param[in] count Number of fields in \a count. + */ +typedef void (*feat_get_call)(struct Client* from, const char* const* fields, int count); +/** Callback to notify of a feature's change. */ typedef void (*feat_notify_call)(void); -/* unmarks all sub-feature values prior to reading .conf */ +/** Unmarks all sub-feature values prior to reading .conf. */ typedef void (*feat_unmark_call)(void); -/* resets to defaults all currently unmarked values */ -typedef int (*feat_mark_call)(int); -/* reports features as a /stats f list */ -typedef void (*feat_report_call)(struct Client*, int); +/** Resets to defaults all currently unmarked values. + * @param[in] marked Non-zero if the feature is marked. + */ +typedef int (*feat_mark_call)(int marked); +/* Reports features as a /stats f list. + * @param[in] sptr Client asking for feature list. + * @param[in] marked Non-zero if the feature is marked. + */ +typedef void (*feat_report_call)(struct Client* sptr, int marked); -#define FEAT_NONE 0x0000 /* no value */ -#define FEAT_INT 0x0001 /* set if entry contains an integer value */ -#define FEAT_BOOL 0x0002 /* set if entry contains a boolean value */ -#define FEAT_STR 0x0003 /* set if entry contains a string value */ -#define FEAT_MASK 0x000f /* possible value types */ +#define FEAT_NONE 0x0000 /**< no value */ +#define FEAT_INT 0x0001 /**< set if entry contains an integer value */ +#define FEAT_BOOL 0x0002 /**< set if entry contains a boolean value */ +#define FEAT_STR 0x0003 /**< set if entry contains a string value */ +#define FEAT_MASK 0x000f /**< possible value types */ -#define FEAT_MARK 0x0010 /* set if entry has been changed */ -#define FEAT_NULL 0x0020 /* NULL string is permitted */ -#define FEAT_CASE 0x0040 /* string is case-sensitive */ +#define FEAT_MARK 0x0010 /**< set if entry has been changed */ +#define FEAT_NULL 0x0020 /**< NULL string is permitted */ +#define FEAT_CASE 0x0040 /**< string is case-sensitive */ -#define FEAT_OPER 0x0100 /* set to display only to opers */ -#define FEAT_MYOPER 0x0200 /* set to display only to local opers */ -#define FEAT_NODISP 0x0400 /* feature must never be displayed */ +#define FEAT_OPER 0x0100 /**< set to display only to opers */ +#define FEAT_MYOPER 0x0200 /**< set to display only to local opers */ +#define FEAT_NODISP 0x0400 /**< feature must never be displayed */ -#define FEAT_READ 0x1000 /* feature is read-only (for now, perhaps?) */ +#define FEAT_READ 0x1000 /**< feature is read-only (for now, perhaps?) */ -static struct FeatureDesc { - enum Feature feat; /* feature identifier */ - char* type; /* string describing type */ - unsigned int flags; /* flags for feature */ - int v_int; /* integer value */ - int def_int; /* default value */ - char* v_str; /* string value */ - char* def_str; /* default value */ - feat_set_call set; /* set feature values */ - feat_set_call reset; /* reset feature values to defaults */ - feat_get_call get; /* get feature values */ - feat_notify_call notify; /* notify of value change */ - feat_unmark_call unmark; /* unmark all feature change values */ - feat_mark_call mark; /* reset to defaults all unchanged features */ - feat_report_call report; /* report feature values */ -} features[] = { +/** Declare a feature with custom behavior. */ #define F_N(type, flags, set, reset, get, notify, unmark, mark, report) \ { FEAT_ ## type, #type, FEAT_NONE | (flags), 0, 0, 0, 0, \ (set), (reset), (get), (notify), (unmark), (mark), (report) } +/** Declare a feature that takes integer values. */ #define F_I(type, flags, v_int, notify) \ { FEAT_ ## type, #type, FEAT_INT | (flags), 0, (v_int), 0, 0, \ 0, 0, 0, (notify), 0, 0, 0 } +/** Declare a feature that takes boolean values. */ #define F_B(type, flags, v_int, notify) \ { FEAT_ ## type, #type, FEAT_BOOL | (flags), 0, (v_int), 0, 0, \ 0, 0, 0, (notify), 0, 0, 0 } +/** Declare a feature that takes string values. */ #define F_S(type, flags, v_str, notify) \ { FEAT_ ## type, #type, FEAT_STR | (flags), 0, 0, 0, (v_str), \ 0, 0, 0, (notify), 0, 0, 0 } +/** Table of feature descriptions. */ +static struct FeatureDesc { + enum Feature feat; /**< feature identifier */ + char* type; /**< string describing type */ + unsigned int flags; /**< flags for feature */ + int v_int; /**< integer value */ + int def_int; /**< default value */ + char* v_str; /**< string value */ + char* def_str; /**< default value */ + feat_set_call set; /**< set feature values */ + feat_set_call reset; /**< reset feature values to defaults */ + feat_get_call get; /**< get feature values */ + feat_notify_call notify; /**< notify of value change */ + feat_unmark_call unmark; /**< unmark all feature change values */ + feat_mark_call mark; /**< reset to defaults all unchanged features */ + feat_report_call report; /**< report feature values */ +} features[] = { /* Misc. features */ F_N(LOG, FEAT_MYOPER, feature_log_set, feature_log_reset, feature_log_get, 0, log_feature_unmark, log_feature_mark, log_feature_report), @@ -356,7 +395,11 @@ static struct FeatureDesc { { FEAT_LAST_F, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }; -/* Given a feature's identifier, look up the feature descriptor */ +/** Given a feature's identifier, look up the feature descriptor. + * @param[in] from Client looking up feature, or NULL. + * @param[in] feature Feature name to find. + * @return Pointer to a FeatureDesc, or NULL if none was found. + */ static struct FeatureDesc * feature_desc(struct Client* from, const char *feature) { @@ -377,7 +420,12 @@ feature_desc(struct Client* from, const char *feature) return 0; /* not found */ } -/* Given a feature vector string, set the value of a feature */ +/** Given a feature vector string, set the value of a feature. + * @param[in] from Client trying to set the feature, or NULL. + * @param[in] fields Parameters to set, starting with feature name. + * @param[in] count Number of fields in \a fields. + * @return Zero (or, theoretically, CPTR_KILLED). + */ int feature_set(struct Client* from, const char* const* fields, int count) { @@ -525,7 +573,12 @@ feature_set(struct Client* from, const char* const* fields, int count) return 0; } -/* reset a feature to its default values */ +/** Reset a feature to its default values. + * @param[in] from Client trying to reset the feature, or NULL. + * @param[in] fields Parameters to set, starting with feature name. + * @param[in] count Number of fields in \a fields. + * @return Zero (or, theoretically, CPTR_KILLED). + */ int feature_reset(struct Client* from, const char* const* fields, int count) { @@ -583,7 +636,12 @@ feature_reset(struct Client* from, const char* const* fields, int count) return 0; } -/* Gets the value of a specific feature and reports it to the user */ +/** Gets the value of a specific feature and reports it to the user. + * @param[in] from Client trying to get the feature. + * @param[in] fields Parameters to set, starting with feature name. + * @param[in] count Number of fields in \a fields. + * @return Zero (or, theoretically, CPTR_KILLED). + */ int feature_get(struct Client* from, const char* const* fields, int count) { @@ -630,7 +688,7 @@ feature_get(struct Client* from, const char* const* fields, int count) return 0; } -/* called before reading the .conf to clear all marks */ +/** Called before reading the .conf to clear all dirty marks. */ void feature_unmark(void) { @@ -643,7 +701,7 @@ feature_unmark(void) } } -/* Called after reading the .conf to reset unmodified values to defaults */ +/** Called after reading the .conf to reset unmodified values to defaults. */ void feature_mark(void) { @@ -685,7 +743,7 @@ feature_mark(void) } } -/* used to initialize the features subsystem */ +/** Initialize the features subsystem. */ void feature_init(void) { @@ -709,7 +767,11 @@ feature_init(void) } } -/* report all F-lines */ +/** Report all F-lines to a user. + * @param[in] to Client requesting statistics. + * @param[in] sd Stats descriptor for request (ignored). + * @param[in] param Extra parameter from user (ignored). + */ void feature_report(struct Client* to, const struct StatDesc* sd, char* param) { @@ -754,7 +816,10 @@ feature_report(struct Client* to, const struct StatDesc* sd, char* param) } } -/* return a feature's integer value */ +/** Return a feature's integer value. + * @param[in] feat &Feature identifier. + * @return Integer value of feature. + */ int feature_int(enum Feature feat) { @@ -764,7 +829,10 @@ feature_int(enum Feature feat) return features[feat].v_int; } -/* return a feature's boolean value */ +/** Return a feature's boolean value. + * @param[in] feat &Feature identifier. + * @return Boolean value of feature. + */ int feature_bool(enum Feature feat) { @@ -777,7 +845,10 @@ feature_bool(enum Feature feat) return features[feat].v_int; } -/* return a feature's string value */ +/** Return a feature's string value. + * @param[in] feat &Feature identifier. + * @return String value of feature. + */ const char * feature_str(enum Feature feat) { -- 2.20.1