From ed5e72004b218d61c633bc1163ab0d5874cb856a Mon Sep 17 00:00:00 2001
From: Justin Seyster <jseyster@cs.sunysb.edu>
Date: Fri, 8 Apr 2011 18:38:29 -0400
Subject: [PATCH] Documentation for the Tracecut extension.

---
 Doxyfile              |  2 +-
 src/aop-doxy-main.c   |  7 +++++++
 src/tracecut-advice.h |  2 +-
 src/tracecut.c        | 29 +++++++++++++++++++++++++++++
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index eac0ab0..0c859d7 100644
--- 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 3a99b5c..e033a0e 100644
--- 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 f5dd535..6dbe2ee 100644
--- 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 0f76c01..89f68cf 100644
--- 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.
+ *
  * \{
  */
 
-- 
2.34.1