From: Justin Seyster Date: Wed, 30 Jun 2010 19:31:23 +0000 (-0400) Subject: Preparations for adding doxygen support. X-Git-Tag: release-v1.0~91^2~2 X-Git-Url: https://git.fsl.cs.stonybrook.edu/?a=commitdiff_plain;h=06988b3d0a35decbe55fdd19c03ddddb2f1b7c2a;p=interaspect.git Preparations for adding doxygen support. Added necessary documentation to aop.h to make doxygen generate browsable HTML documentation. --- diff --git a/src/aop-weave.c b/src/aop-weave.c index 4016a06..ce2d86c 100644 --- a/src/aop-weave.c +++ b/src/aop-weave.c @@ -175,23 +175,13 @@ op_default_prepare_for_weave (struct aop_joinpoint *jp) * must be the last argument to aop_insert_advice(), even when not * specifying any arguments for the advice function. * - * Specifying AOP_INSERT_BEFORE or AOP_INSERT_AFTER will place the - * call before or after the join point (when possible) and will - * guarantee certain properties about ordering of advice calls. Using - * AOP_INSERT_BEFORE to insert multiple advice calls at the same join - * point will place advice calls in the order they are inserted. With - * AOP_INSERT_AFTER, however, advice calls will be placed in _reverse_ - * order. No matter what order calls are inserted in, all - * AOP_INSERT_BEFORE calls will be placed before all AOP_INSERT_AFTER - * calls. - * - * It is legal to use AOP_INSERT_BEFORE and AOP_INSERT_AFTER to - * enforce ordering among advice calls even when inserting before or - * after a join point does not make sense. For example, it does not - * make sense to insert an advice call before a function entry join - * point. Using AOP_INSERT_BEFORE will still insert the advice after - * function entry, but it will place the advice before any - * AOP_INSERT_AFTER advice. + * \param jp The join point to instrument with advice. + * \param func_name The name of the advice function. + * \param location Where to insert advice with respect to the join + * point. See the documenation for enum #aop_insert_location for more + * detail. + * \param ... A list of arguments to pass to the advice function, + * terminated by #AOP_TERM_ARG. */ void aop_insert_advice (struct aop_joinpoint *jp, const char *func_name, diff --git a/src/aop.h b/src/aop.h index 62692c1..0daf775 100644 --- a/src/aop.h +++ b/src/aop.h @@ -29,17 +29,56 @@ calls can pass values from the running program to the advice function. */ -/* Client plug-in _must_ include this line to indicate that it is - GPLv3 compatible.*/ +/** + * \file aop.h + * \brief The entire InterAspect public interface. + * + * Include aop.h for all functions and data types necessary for an + * InterAspect plug-in. It is not generally necessary to include any + * other InterAspect header files or any GCC header files. + */ + +/** + * \brief Client plug-in must use this macro to indicate that + * it is GPLv3 compatible. + * + * GCC will refuse to execute plug-ins that do not declare themselves + * as GPL compatible. Call this macro at the top level of any one + * source file in a plug-in to declare the plug-in as GPL compatible. + * + * By using this macro, you state that, if you distribute your + * plug-in, you will not distribute it under any terms that are + * incompatible with the GPL. This is a requirement of the GCC + * license. Contact the Free Software Foundation for more + * information. (The InterAspect team is not affiliated with the Free + * Software Foundation.) + */ #define AOP_I_AM_GPL_COMPATIBLE() \ __attribute__((visibility("default"))) int plugin_is_GPL_compatible; -/* Define aop_main using the AOP_MAIN_PROTO macro. Absolutely do not - just declare it as a void function! */ +/** + * \brief A macro for easily declaring a plug-in's main function. + * + * Define aop_main using the AOP_MAIN_PROTO macro to enusre that its + * linker visibility is set correctly. Absolutely do not just declare + * it as a void function! + * + * For example: + * \code + * AOP_PROTO_MAIN aop_main(void) + * \endcode +*/ #define AOP_MAIN_PROTO __attribute__((visibility("hidden"))) void /* This assertion routine is mostly copied from gcc/system.h */ #ifndef AOP_NO_ASSERT_CHECK + +/** + * \brief A convenient interface to GCC's assertion facility. + * + * If EXPR evaluates to false, GCC will abort compilation and show an + * error with the file and line number of the failed assertion. + */ #define aop_assert(EXPR) \ ((void)(!(EXPR) ? aop_abort (__FILE__, __LINE__, __FUNCTION__), 0 : 0)) #else /* AOP_NO_ASSERT_CHECK */ @@ -52,15 +91,71 @@ struct aop_joinpoint; struct aop_pointcut; struct aop_type; +/** + * \brief Type for plug-in pass functions. + * + * The function type for pass functions to be registered with + * aop_register_pass(). + */ typedef unsigned int (*pass_callback) (); + +/** + * \brief Type for aop_join_on() callbacks. + * + * The function type for callback functions to be used for iterating + * over a pointcut with aop_join_on(). + */ typedef void (*join_callback) (struct aop_joinpoint *, void *callback_param); extern void aop_filter_include_temps (struct aop_pointcut *pc); extern void aop_filter_exclude_temps (struct aop_pointcut *pc); +/** + * \brief Advice locations for aop_insert_advice(). + * + * Specifying AOP_INSERT_BEFORE or AOP_INSERT_AFTER will place the + * call before or after the join point (when possible) and will + * guarantee certain properties about ordering of advice calls. Using + * AOP_INSERT_BEFORE to insert multiple advice calls at the same join + * point will place advice calls in the order they are inserted. With + * AOP_INSERT_AFTER, however, advice calls will be placed in _reverse_ + * order. No matter what order calls are inserted in, all + * AOP_INSERT_BEFORE calls will be placed before all AOP_INSERT_AFTER + * calls. + * + * It is legal to use AOP_INSERT_BEFORE and AOP_INSERT_AFTER to + * enforce ordering among advice calls even when inserting before or + * after a join point does not make sense. For example, it does not + * make sense to insert an advice call before a function entry join + * point. Using AOP_INSERT_BEFORE will still insert the advice after + * function entry, but it will place the advice before any + * AOP_INSERT_AFTER advice. + */ enum aop_insert_location { + /** + * \brief Insert advice before a join point when possible. + * + * Even when it does not make sense to insert advice before a join + * point, all #AOP_INSERT_BEFORE advice will be ordered before all + * #AOP_INSERT_AFTER advice. + * + * If multiple advice calls are inserted with #AOP_INSERT_BEFORE, + * they will be placed in the order they were inserted. + */ AOP_INSERT_BEFORE, - AOP_INSERT_AFTER + + /** + * \brief Insert advice after a join point when possible. + * + * Even when it does not make sense to insert advice before a join + * point, all #AOP_INSERT_BEFORE advice will be ordered before all + * #AOP_INSERT_AFTER advice. + * + * If multiple advice calls are inserted with #AOP_INSERT_AFTER, + * they will be placed in the reverse of the order they were + * inserted in. + */ + AOP_INSERT_AFTER, }; extern void aop_insert_advice (struct aop_joinpoint *jp, const char *name, @@ -88,7 +183,22 @@ enum aop_argkind { AOP_TERM_ARG, }; +/** + * \brief Mark an advice argument as a string constant + * (const char *). + * + * Use this macro when passing a string constant (const char *) + * argument to aop_insert_advice(). + */ #define AOP_STR_CST(VAL) ATA_STR_CST, VAL + +/** + * \brief Mark an advice argument as an runtime value + * (struct aop_dynval *). + * + * Use this macro when passing a runtime value + * (struct aop_dynval *) argument to aop_insert_advice(). + */ #define AOP_DYNVAL(VAL) ATA_DYNVAL, VAL extern const char *aop_capture_function_name (struct aop_joinpoint *jp);