[asterisk-commits] twilson: branch twilson/config_work r365708 - /team/twilson/config_work/inclu...

[SVN commits to the Asterisk project]

Author: twilson
Date: Tue May  8 15:44:20 2012
New Revision: 365708

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=365708
Log:
Add more macro definition and cleanup

Modified:
    team/twilson/config_work/include/asterisk/config_options.h

Modified: team/twilson/config_work/include/asterisk/config_options.h
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_work/include/asterisk/config_options.h?view=diff&rev=365708&r1=365707&r2=365708
==============================================================================
--- team/twilson/config_work/include/asterisk/config_options.h (original)
+++ team/twilson/config_work/include/asterisk/config_options.h Tue May  8 15:44:20 2012
@@ -398,6 +398,10 @@
 
 /*! \def ARGMAP(func, func_arg, x, ...)
  * \brief Map \a func(\a func_arg, field) across all fields including \a x
+ * \param func The function (almost certainly offsetof) to map across the fields
+ * \param func_arg The first argument (almost certainly a type (e.g. "struct mystruct")
+ * \param x The first field
+ * \param varargs The rest of the fields
  *
  * Example usage:
  *     struct foo {
@@ -412,20 +416,41 @@
  *
  * The macro isn't limited to offsetof, but that is the only purpose for
  * which it has been tested.
+ *
+ * As an example of how the processing works:
+ *
+ * ARGMAP(offsetof, struct foo, a, b, c) ->
+ * ARGMAP_(3, offsetof, struct foo, a, b, c) ->
+ * ARGMAP_3(offsetof, struct foo, 3, a, b, c) ->
+ * ARGMAP_2(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a)), b, c) ->
+ * ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) ->
+ * ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) ->
+ * 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)
  */
 #define ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
 
-/* This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so
+/* \note This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so
  * that the accumulation both works properly for the first argument (since "in" can't be empty) and
  * we get the number of arguments in our varargs as a bonus */
 #define ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)
 
-/* Two levels to handler the case where arg1 and arg2 are macros themselves */
+/*! \def PASTE(arg1, arg2)
+ * \brief Paste two arguments together, even if they are macros themselves
+ * \note Uses two levels to handle the case where arg1 and arg2 are macros themselves
+ */
 #define PASTE(arg1, arg2)  PASTE1(arg1, arg2)
 #define PASTE1(arg1, arg2) arg1##arg2
 
+/*! \brief Take a comma-separated list and allow it to be passed as a single argument to another macro */
 #define ARGIFY(...) __VA_ARGS__
 
+/*! \brief The individual field handlers for ARGMAP
+ * \param func The function (most likely offsetof)
+ * \param func_arg The first argument to func (most likely a type e.g. "struct my_struct")
+ * \param in The accumulated function-mapped field names so far
+ * \param x The next field name
+ * \param varargs The rest of the field names
+ */
 #define ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x))
 #define ARGMAP_2(func, func_arg, in, x, ...)\
 	ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
@@ -442,7 +467,7 @@
 #define ARGMAP_8(func, func_arg, in, x, ...)\
 	ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
-/* \def VA_NARGS(...)
+/*! \def VA_NARGS(...)
  * \brief Results in the number of arguments passed to it
  * \note Currently only up to 8, but expanding is easy. This macro basically counts
  * commas + 1. To visualize:
@@ -462,13 +487,47 @@
 #define VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
 #define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N
 
+/*! \def FLDSET(type, ...)
+ * \brief Convert a struct and list of fields to an argument list of field offsets
+ * \param type The type with the fields (e.g. "struct my_struct")
+ * \param varags The fields in the struct whose offsets are needed as arguments
+ * 
+ * For example:
+ * \code
+ * struct foo {int a, char b[128], char *c};
+ * FLDSET(struct foo, a, c)
+ * \endcode
+ *
+ * produces
+ * \code
+ * offsetof(struct foo, a), offsetof(struct foo, c)
+ * \endcode
+ */
 #define FLDSET(type, ...) FLDSET1(type, ##__VA_ARGS__)
-#define FLDSET1(type, ...) POP(ARGIFY(ARGMAP(offsetof, type, ##__VA_ARGS__)))
-
+#define FLDSET1(type, ...) POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))
+
+/*! \def STRFLDSET(type, ...)
+ * \brief Convert a struct and a list of stringfield fields to an argument list of field offsets
+ * \note Stringfields require the passing of the field manager pool, and field manager to the
+ * default stringfield option handler, so registering options that point to stringfields requires
+ * this macro to be called instead of the FLDSET macro.
+ * \param type The type with the fields (e.g. "struct my_struct")
+ * \param varargs The fields in the struct whose offsets are needed as arguments
+ */
 #define STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
 
-#define POP(...) POP1(__VA_ARGS__)
-#define POP1(x, ...) __VA_ARGS__
+/*! \def POPPED(...)
+ * \brief A list of arguments without the first argument
+ * \note Used internally to remove the leading "number of arguments" argument from ARGMAP for
+ * FLDSET. This is because a call to FLDSET may be followed by additional arguments in
+ * aco_register_option, so the true number of arguments will possibly be different than what
+ * ARGMAP returns.
+ * \params varags A list of arguments
+ *
+ * POPPED(a, b, c) -> b, c
+ */
+#define POPPED(...) POPPED1(__VA_ARGS__)
+#define POPPED1(x, ...) __VA_ARGS__
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }