Fix documentation, add notes about a trace list limitations

Author: chad-earthscope

doc/examples.dox

@@ -84,6 +84,11 @@ An input file of miniSEED is used as a convenient data source.
 ::MS3Record containers can be constructed for any arbitrary data and
 follow the same pattern of record generation.
 
+@note The ::MS3TraceList data structure is designed as a container of data
+sample payloads (integers, floats, text). A trace list does not contain all of
+the details of miniSEED records and cannot be used to represent and create
+header-only miniSEED records or records with custom header flags.
+
 @include lm_pack_rollingbuffer.c
 
 @section example-lm_sids Working with Source Identifiers

genutils.c

@@ -1034,6 +1034,7 @@ ms_nstime2time (nstime_t nstime, uint16_t *year, uint16_t *yday, uint8_t *hour,
  *
  * @param[in] nstime Time value to convert
  * @param[out] timestr Buffer for ISO time string
+ * @param[in] timestrsize Size of the \a timestr buffer in bytes
  * @param timeformat Time string format, one of @ref ms_timeformat_t
  * @param subseconds Inclusion of subseconds, one of @ref ms_subseconds_t
  *

libmseed.h

@@ -556,8 +556,8 @@ typedef struct MS3RecordList
 
     Trace lists are a container to organize continuous segments of
     data.  By combining miniSEED data records into trace lists, the
-    time series is reconstructed and ready for processing or
-    summarization.
+    time series is reconstructed and ready for processing, conversion,
+    summarization, etc.
 
     A trace list container starts with an ::MS3TraceList, which
     contains one or more ::MS3TraceID entries, which each contain one
@@ -576,6 +576,10 @@ typedef struct MS3RecordList
           - ...
         - ...
 
+    @note A trace list does not contain all of the details of a miniSEED
+    record.  In particular details that are not relevant to represent the series
+    such as header flags, extra headers like event detections, etc.
+
     \sa ms3_readtracelist()
     \sa ms3_readtracelist_timewin()
     \sa ms3_readtracelist_selection()

tracelist.c

@@ -712,53 +712,45 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
 /** ************************************************************************
  * @brief Add data coverage from an ::MS3Record to a ::MS3TraceList
  *
- * Searching the list for the appropriate ::MS3TraceID and
- * ::MS3TraceSeg and either add data to existing entries or create new
- * ones as needed.
- *
- * As this routine adds data to a trace list it constructs continuous
- * time series, merging segments when possible.  The \a tolerance
- * pointer to a ::MS3Tolerance identifies function pointers that are
- * expected to return time tolerance, in seconds, and sample rate
- * tolerance, in Hertz, for the given ::MS3Record.  If \a tolerance is
- * NULL, or the function pointers it identifies are NULL, default
- * tolerances will be used as follows: - Default time tolerance is 1/2
- * the sampling period - Default sample rate (sr) tolerance is
+ * Searching the list for the appropriate ::MS3TraceID and ::MS3TraceSeg and
+ * either add data to existing entries or create new ones as needed.
+ *
+ * As this routine adds data to a trace list it constructs continuous time
+ * series, merging segments when possible.  The \a tolerance pointer to a
+ * ::MS3Tolerance identifies function pointers that are expected to return time
+ * tolerance, in seconds, and sample rate tolerance, in Hertz, for the given
+ * ::MS3Record.  If \a tolerance is NULL, or the function pointers it identifies
+ * are NULL, default tolerances will be used as follows: - Default time
+ * tolerance is 1/2 the sampling period - Default sample rate (sr) tolerance is
  * abs(1‐sr1/sr2) < 0.0001
  *
- * In recommended usage, the \a splitversion flag is \b 0 and
- * different publication versions of otherwise matching data are
- * merged.  If more than one version contributes to a given source
- * identifier's segments, its ::MS3TraceID.pubversion will be the set to
- * the largest contributing version.  If the \a splitversion flag is
- * \b 1 the publication versions will be kept separate with each
- * version isolated in separate ::MS3TraceID entries.
- *
- * If the \a autoheal flag is true, extra processing is invoked to
- * conjoin trace segments that fit together after the ::MS3Record
- * coverage is added.  For segments that are removed, any memory at
- * the ::MS3TraceSeg.prvtptr will be freed.
- *
- * The lists are always maintained in a sorted order.  An
- * ::MS3TraceList is maintained with the ::MS3TraceID entries in
- * ascending alphanumeric order of SID. If repeated SIDs are present
- * due to splitting on publication version, they are maintained in
- * order of ascending version.  A ::MS3TraceID is always maintained
- * with ::MS3TraceSeg entries in data time time order.
+ * In recommended usage, the \a splitversion flag is \b 0 and different
+ * publication versions of otherwise matching data are merged.  If more than one
+ * version contributes to a given source identifier's segments, its
+ * ::MS3TraceID.pubversion will be the set to the largest contributing version.
+ * If the \a splitversion flag is \b 1 the publication versions will be kept
+ * separate with each version isolated in separate ::MS3TraceID entries.
+ *
+ * @note The ::MS3TraceList data structure is designed as a container of data
+ * sample payloads (integers, floats, text) unrelated to miniSEED records.  Many
+ * of the details in a miniSEED record that are not relevant to represent the
+ * series are not stored in the trace list, and therefore, will not be included
+ * in an output such as miniSEED produced by mstl3_pack().
+ *
+ * While header-only miniSEED records, with no data payload, can be added to a
+ * trace list they will be represented as empty segments with no time coverage
+ * for informational purposes.
  *
  * @param[in] mstl Destination ::MS3TraceList to add data to
  * @param[in] msr ::MS3Record containing the data to add to list
- * @param[in] pprecptr Pointer to pointer to a ::MS3RecordPtr for @ref record-list
  * @param[in] splitversion Flag to control splitting of version/quality
  * @param[in] autoheal Flag to control automatic merging of segments
  * @param[in] flags Flags to control optional functionality (unused)
  * @param[in] tolerance Tolerance function pointers as ::MS3Tolerance
  *
  * @returns a pointer to the ::MS3TraceSeg updated or NULL on error.
  *
- * \sa mstl3_addmsr_recordptr()
- * \sa mstl3_readbuffer()
- * \sa ms3_readtracelist()
+ * \sa mstl3_addmsr_recordptr() \sa mstl3_readbuffer() \sa ms3_readtracelist()
  *
  * \ref MessageOnError - this function logs a message on error
  ***************************************************************************/
@@ -770,7 +762,7 @@ mstl3_addmsr (MS3TraceList *mstl, const MS3Record *msr, int8_t splitversion, int
 }
 
 /** ************************************************************************
- * @copydoc mstl3_pack()
+ * @copydoc mstl3_addmsr()
  *
  * This function is identical to mstl3_addmsr() but with the additional \a
  * pprecptr parameter: