Documentation for the Tracecut extension.

diff --git a/Doxyfile b/Doxyfile
index eac0ab0a8a5b3ee0a9c34094e1176be487ab3e0f..0c859d756da0a8225b791a5bfa292d6dff99d4eb 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -611,7 +611,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = tracecut-advice.? nfa.c
+EXCLUDE_PATTERNS       = tracecut-advice.c nfa.c
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

diff --git a/src/aop-doxy-main.c b/src/aop-doxy-main.c
index 3a99b5c9cd74e5494d1a6e2c602ab2cf187e3954..e033a0ef3c5436c7ca24a1bc5f9d061336231e96 100644 (file)
--- a/src/aop-doxy-main.c
+++ b/src/aop-doxy-main.c
@@ -142,6 +142,13 @@
  * ensuring that advice functions and the functions they call do not
  * themselves get instrumented (which can cause unbounded recursion
  * and other problems).
+ *
+ * \section ia_tracecut Tracecut Extension
+ *
+ * New to InterAspect 1.1 is the InterAspect Tracecut extension.
+ * Tracecuts let you specify program monitors as regular expressions
+ * over program events.  See the \ref tracecut function documentation
+ * and the \ref fclose_tracecut.c "fclose_tracecut" sample plug-in.
  */
 
 /**

diff --git a/src/tracecut-advice.h b/src/tracecut-advice.h
index f5dd535b0048092df30ed71cfa925554b1ff95e9..6dbe2ee6f7134770095a0f066b836af8fb9cc923 100644 (file)
--- a/src/tracecut-advice.h
+++ b/src/tracecut-advice.h
@@ -27,7 +27,7 @@
 
 /**
  * \file tracecut-advice.h
- * \brief Public interface for implementing tracut advice functions.
+ * \brief Public interface for implementing tracecut advice functions.
  *
  * When the tracecut monitoring engine matches a tracecut rule, it
  * calls the tracecut match function, tc_report_match().  By default,

diff --git a/src/tracecut.c b/src/tracecut.c
index 0f76c013bf2705d749d9e73290927edb857e470c..89f68cf1c338864c87c6f28a67733b154042e743 100644 (file)
--- a/src/tracecut.c
+++ b/src/tracecut.c
@@ -104,6 +104,35 @@ struct tc_tracecut {
 
 /**
  * \defgroup tracecut Tracecut Functions
+ *
+ * In InterAspect, a tracecut specifies a program property as a
+ * regular expression.  At runtime, there is a tracecut monitor, which
+ * is modeled as a finite-state machine, that detects whenever the
+ * tracecut regular expression matches some sequence of program events.
+ *
+ * It is possible to independently monitor the same property on
+ * multiple program objects by parameterizing the tracecut.  The
+ * tracecut engine spawns a new monitor instance for each distinct set
+ * of parameters.  For example, you could design a tracecut that
+ * creates a monitor instance for each FILE object, as is done in the
+ * \ref fclose_tracecut.c "fclose_tracecut" sample tracecut plug-in.
+ *
+ * The easiest way to define a tracecut is by first defining all the
+ * parameters, and then adding call symbols with
+ * tc_declare_call_symbol().  Each symbol represents a particular
+ * program event (a call to a specified function) that you can
+ * reference in a regular expression rule.
+ *
+ * When you compile a target program with a tracecut plug-in, you must
+ * also link the target program with the tracecut monitoring engine
+ * library, <code>-ltracecut</code>.
+ *
+ * When a tracecut rule matches, the monitoring engine calls the
+ * tracecut advice function, tc_report_match(), which prints a message
+ * to <code>stderr</code> by default.  The tc_report_match() function
+ * is defined as a weak symbol, so you can override it by defining
+ * your own version.
+ *
  * \{
  */