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 4016a06683720ff8d90ebb4f084088fe7cbf872b..ce2d86c9b7571f0b307335776061ba99adc66376 100644 (file)
--- 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 62692c12a6df3fb4f339a1830772f7b613dc3372..0daf7758651d7ec11d352b7e3c25d24938b2ab76 100644 (file)
--- 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 <i>must</i> 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 <i>reverse</i> 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);