Commit 1ea51f24 authored by thomas.forbriger's avatar thomas.forbriger
Browse files

[WP][DOC] (ticket10tsio): document gross structure of modules

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.

The gross structure of the modules is documented.
I intend to reorganize the namespaces accordingly.
Probably filenames should be considered for modification too.

Form doxygen.txt:
Two modules are provided:

 in sffheaders.h:
    SFF Timeseries I/O This module provides three submodules:
        A set of classes to handle complete files
        Interface to libdatrwxx
        Interface to libsffxx
 in readtsdata.h:
    Reading of time series data.

The first adds SFF specific headers to the TimeSeries class template provided
by libtsxx. It adds further structures to hold data from complete time series
data files. For input and output of complete files, appropriate i/o operators
are provided for libdatrwxx streams. Trace selection is supported.

The latter module adds further data to the file classes provided by the first
modules. Additionally it provides reading functions (not writing functions)
which in the end support the reading of all time series data files provided on
the command line together with all file specific flags and parameters and
selecting traces.
parent 4b56e6a1
......@@ -45,6 +45,26 @@ be updated.
Other functionality provides the input and output of complete data files with
trace selection in one line of code.
Two modules are provided:
- \ref group_sffheaders
This module provides three submodules:
- \ref subgroup_sffheaders_classes
- \ref subgroup_sffheaders_datrwxx
- \ref subgroup_sffheaders_sffxx
- \ref group_readtsdata
The first adds SFF specific headers to the TimeSeries class template provided
by libtsxx. It adds further structures to hold data from complete time series
data files. For input and output of complete files, appropriate i/o operators
are provided for libdatrwxx streams. Trace selection is supported.
The latter module adds further data to the file classes provided by the first
modules.
Additionally it provides reading functions (not writing functions) which in
the end support the reading of all time series data files provided on the
command line together with all file specific flags and parameters and
selecting traces.
\section main_history History
These modules previously were implemented in libtsxx and libtfxx.
......
......@@ -60,6 +60,12 @@
*
* The module is presented in namespace tfxx::tsio.
*
* This module is presented in file readtsdata.h
*
* It is placed ton top of the module presented in sffheaders.h
* and supports to read a complete set of files as presented on the command
* line together with all file specific parameters and trace selectors.
*
*/
namespace tsio {
......
/*! \file sffheaders.h
* \brief provide full sffheaders (prototypes)
* \ingroup group_sffts
* \ingroup group_sffheaders
*
* ----------------------------------------------------------------------------
*
......@@ -58,25 +58,14 @@
/*! \brief SFF Timeseries I/O.
*
* \defgroup group_sffts SFF Timeseries I/O
* \defgroup group_sffheaders SFF Timeseries I/O
*
* Input and output
*/
/*! \brief Interface to libdatrwxx
* This interface is presented in sffheaders.h
*
* \defgroup subgroup_datrwxx Interface to libdatrwxx
* \ingroup group_sffts
*
* Input and output
*/
/*! \brief Interface to libsffxx
*
* \defgroup subgroup_sffxx Interface to libsffxx
* \ingroup group_sffts
*
* Input and output
* This module provides three submodules:
* - \ref subgroup_sffheaders_classes
* - \ref subgroup_sffheaders_datrwxx
* - \ref subgroup_sffheaders_sffxx
*/
namespace tsio {
......@@ -85,8 +74,28 @@ namespace tsio {
*/
namespace sff {
/*! hold information for a complete SFF file header
* \ingroup group_sffts
/*! \brief A set of classes to handle complete files
*
* \defgroup subgroup_sffheaders_classes A set of classes to handle complete files
* \ingroup group_sffheaders
*
* As a basis for time series processing, it provides the class template
* SFFTimeSeries which inherits from ts::TimeSeries and this way is a fully
* qualified TimeSeries class in terms of libtsxx.
* SFFTimeSeries can be passed directly for filter modules and other modules
* in libtsxx.
* In contrast to the basic TimeSeries class definitions in libtsxx,
* SFFTimeSeries is equipped with an SFF TraceHeader.
*
* By combining several SFFTimeSeries objects to a TraceVector, a set of
* traces can be stored and passed along.
* A TraceVector together with a FileHeader builds a data File.
*
* @{
*/
/*! \brief hold information for a complete SFF file header
* \ingroup group_sffheaders_classes
*/
class FileHeader {
public:
......@@ -108,8 +117,8 @@ namespace tsio {
/*----------------------------------------------------------------------*/
/*! hold information for a complete SFF trace header
* \ingroup group_sffts
/*! \brief hold information for a complete SFF trace header
* \ingroup group_sffheaders_classes
*/
class TraceHeader {
public:
......@@ -134,8 +143,8 @@ namespace tsio {
/*----------------------------------------------------------------------*/
/*! hold a full SFF trace and provide conversion
* \ingroup group_sffts
/*! \brief hold a full SFF trace and provide conversion
* \ingroup group_sffheaders_classes
*/
template<class C>
class SFFTimeSeries:
......@@ -164,8 +173,8 @@ namespace tsio {
/*----------------------------------------------------------------------*/
/*! hold SFF traces with full header information
* \ingroup group_sffts
/*! \brief hold SFF traces with full header information
* \ingroup group_sffheaders_classes
*/
template<class C>
class TraceVector: public std::vector<SFFTimeSeries<C> > {
......@@ -176,8 +185,10 @@ namespace tsio {
/*----------------------------------------------------------------------*/
/*! hold all information contained in an SFF data file
* \ingroup group_sffts
/*! \brief hold all information contained in an SFF data file
* \ingroup group_sffheaders_classes
*
* Store the complete information contained in a data file
*/
template<class C>
struct File: public TraceVector<C> {
......@@ -194,6 +205,22 @@ namespace tsio {
FileHeader fileheader;
}; // struct File
/*!
* @}
*/
/*======================================================================*/
/*! \brief Interface to libdatrwxx
*
* \defgroup subgroup_sffheaders_datrwxx Interface to libdatrwxx
* \ingroup group_sffheaders
*
* Input/output operators for structures in \ref group_sffheaders_classes
* to libdatrwxx input/output streams.
* @{
*/
/*======================================================================*/
// libdatrwxx input operators
......@@ -209,10 +236,6 @@ namespace tsio {
/*======================================================================*/
// libdatrwxx output operators
/*! \addtogroup group_sffts
* @{
*/
inline
datrw::odatstream& operator<<(datrw::odatstream& os,
......@@ -279,6 +302,27 @@ namespace tsio {
const File<C>& f)
{ return(os << f.fileheader << TraceVector<C>(f)); }
/*!
* @}
*/
/*======================================================================*/
/*! \brief Interface to libsffxx
*
* \defgroup subgroup_sffheaders_sffxx Interface to libsffxx
* \ingroup group_sffheaders
*
* Output operators for classes in module \ref subgroup_sffheaders_classes
* to SFFostream from libsff
*
* \deprecated
* Direct output to libsffxx through SFFostream is deprecated.
* Use output through libdatrwxx streams instead.
* Appropriate operators are presented in module
* \ref subgroup_sffheaders_datrwxx
* @{
*/
/*======================================================================*/
// sff::SFFostream output operators
......@@ -303,15 +347,7 @@ namespace tsio {
return os;
}
/*!
* @}
*/
/*----------------------------------------------------------------------*/
/*! \addtogroup subgroup_sffxx
* @{
*/
/*! \note
* The compiler cannot distinguish between this definition and the
......@@ -355,13 +391,15 @@ namespace tsio {
const File<C>& f)
{ return(os << f.fileheader << TraceVector<C>(f)); }
/*!
* @}
*/
/*!
* @}
*/
/*======================================================================*/
// member functions
/*! \brief Read a complete file with all traces.
*/
template<class C>
inline void File<C>::read(datrw::idatstream& is, const bool& verbose)
{
......@@ -371,6 +409,9 @@ namespace tsio {
/*----------------------------------------------------------------------*/
/*! \brief Read a data file an extract selected traces.
*/
template<class C>
inline void File<C>::read(datrw::idatstream& is,
const Trangelist& rl,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment