Documentation update

README.md

@@ -141,18 +141,10 @@ program context combined with measurement data. When snapshots are
 taken, what is included in them, and how they are processed depends on
 the Caliper runtime configuration. It is thus important to configure
 the runtime correctly when running a Caliper-instrumented program.
-
-Much of Caliper's functionality is provided by optional service
-modules. By default, Caliper does not enable any optional services
-(and therefore doesn't do much). Use the `CALI_SERVICES_ENABLE`
-variable to select services. For example, enable the `event`,
-`recorder` and `timestamp` services to create a simple time-series
-trace for the example program above:
-
-    $ export CALI_SERVICES_ENABLE=event:recorder:timestamp
-
-You can achieve the same effect by selecting the `serial-trace`
-built-in profile:
+For common use cases, Caliper provides built-in configuration profiles
+as starting points. For example, the `serial-trace` profile will 
+record a time-stamped event trace. You can select a profile with the 
+`CALI_CONFIG_PROFILE` environment variable:
 
     $ export CALI_CONFIG_PROFILE=serial-trace
 
@@ -165,7 +157,7 @@ Then run the program:
     == CALIPER: Wrote 36 records.
     == CALIPER: Finished
 
-The recorder service will write the time-series trace to a `.cali`
+With this profile, Caliper will write a time-series trace to a `.cali`
 file in the current working directory. Use the `cali-query` tool to
 filter, aggregate, or print traces:
 
@@ -204,9 +196,9 @@ Here is a list of commonly used variables:
   informational output, 2 for more verbose output, or 0 to disable
   output except for critical error messages. Default 1.
 
-* `CALI_SERVICES_ENABLE=(service1:service2:...)` List of Caliper service modules to enable,
-  separated by `:`. Default: not set, no service modules enabled. See
-  below for a list of Caliper services.
+* `CALI_SERVICES_ENABLE=(service1:service2:...)` List of Caliper service 
+  modules to enable, separated by `:`. Default: not set, no service modules 
+  enabled. See below for a list of Caliper services.
 
 ### List of Caliper services
 
@@ -216,6 +208,9 @@ capabilities. The flexible combination and configuration of these
 services allows you to quickly assemble recording solutions for a wide
 range of usage scenarios.
 
+Many of the services provide additional configuration options. Refer to 
+the service documentation to learn more.
+
 You can enable the services required for your measurement with the
 `CALI_SERVICES_ENABLE` configuration variable
 
@@ -236,7 +231,8 @@ The following services are available:
   A thread environment manager such as the `pthread` service creates
   separate per-thread contexts in a multi-threaded program.
 * `papi` Records PAPI hardware counters.
-* `recorder` Writes context trace data.
+* `recorder` Writes data to disk
+* `trace` Creates a trace of snapshots
 * `timestamp` The timestamp service adds a time offset, timestamp,
   or duration to context records.
 

doc/services.rst

@@ -180,9 +180,9 @@ recommended to enable the `pthread` service.
 Recorder
 --------------------------------
 
-The recorder service writes context snapshots into a context trace file.
+The recorder service writes Caliper I/O records into a file.
 
-By default, the recorder service stores context records in an
+By default, the recorder service stores records in an
 in-memory buffer to avoid application performance perturbance because
 of I/O. You can configure the buffer sizes and determine whether they
 are allowed to grow. You can also set the directory and filename that
@@ -226,8 +226,8 @@ Configuration
 ................................
 
 CALI_TIMER_DURATION=(true|false)
-  Include duration (in microseconds) of the context epoch in context
-  snapshots. Default: true
+  Measure duration (in microseconds) of the context epoch (i.e., the time
+  between two consecutive context snapshots). Default: true
 
 CALI_TIMER_OFFSET=(true|false)
   Include the time offset (time since program start, in microseconds)
@@ -236,4 +236,15 @@ CALI_TIMER_OFFSET=(true|false)
 CALI_TIMER_TIMESTAMP=(true|false)
   Include absolute timestamp (time since UNIX epoch, in seconds) with each
   context snapshot.
+
+CALI_TIMER_PHASE_DURATION
+  Measure the duration of begin/end, set/set, or set/end phases. The 
+  event service with event trigger information generation needs to be 
+  enabled for this feature.
 
+Trace
+--------------------------------
+
+The trace service creates an I/O record for each snapshot. With the
+`recorder` sercice enabled, this will create a snapshot trace file.
+

src/caliper/Caliper.h

@@ -1,5 +1,5 @@
 /** 
- * @file caliper.h 
+ * @file Caliper.h 
  * Initialization function and global data declaration
  */