libstfinv [WP][DOC]: outline Fourier domain input and output procedure

src/libs/libstfinv/stfinvfourier.cc

@@ -167,13 +167,21 @@ namespace stfinv {
    *    next integer multiple of the divisor larger than fpad*nsamples.
    *
    * \par Workspace
-   * Two FFT engines will be created:
+   * Two FFT engines will be created.
+   * They are only used one-way, since input data is not altered during
+   * processing input time series only have to be transformed once to Fourier
+   * domain.
+   * Results of processing have to be transformed to time domain.
    * -# One engine (\c STFFourierDomainEngine::Mfftengineinput) being shared
    *  by recorded data and synthetic data, because both have to be transformed
    *  to Fourier domain at once.
+   *  Transformation to Fourier domain takes place in
+   *  STFFourierDomainEngine::fftinput.
    * -# One engine (\c STFFourierDomainEngine::Mfftengineoutput) being shared
    *  by the stf and the convolved synthetics, because both have to be
    *  transformed to the time domain at once.
+   *  Transformation to time domain takes place in
+   *  STFFourierDomainEngine::fftoutput.
    */
   void STFFourierDomainEngine::initialize()
   {
@@ -261,6 +269,16 @@ namespace stfinv {
 
   /*----------------------------------------------------------------------*/
 
+  /*!
+   * Provide data passed (through the API) by the caller of the library to an
+   * engine operating in the Fourier domain.
+   * All input is available as time series data in first place.
+   * -# Copy time series data to STFFourierDomainEngine::Mfftengineinput
+   * -# Transform time series data to Fourier domain
+   *
+   * This function should be called by the very first statement of the
+   * exec-function of the derived class (e.g. STFEngineFDLeastSquares::exec).
+   */
   void STFFourierDomainEngine::fftinput()
   {
     this->getinput();
@@ -269,6 +287,19 @@ namespace stfinv {
 
   /*----------------------------------------------------------------------*/
 
+  /*!
+   * Provide results of Fourier domain operation to the caller of the library.
+   * -# Apply time domain taper to correction filter, if requested
+   * -# Apply convolution with correction filter response to all synthetic
+   *    input data
+   * -# Apply time shift to impulse response of correction filter, if
+   *    requested
+   * -# Transform Fourier series to time domain
+   * -# Copy time series data to buffer array accessible through API
+   *
+   * This function should be called by the very last statement of the
+   * exec-function of the derived class (e.g. STFEngineFDLeastSquares::exec).
+   */
   void STFFourierDomainEngine::fftoutput()
   {
     // NOTE: apply taper here
@@ -369,6 +400,8 @@ namespace stfinv {
   void STFFourierDomainEngine::getinput()
   {
     // clear workspace through reference
+    // (remark: return value sarray is a reference to an array addressing all
+    // samples of all time series contained in Mfftengineinput)
     TAseries sarray=Mfftengineinput.series();
     sarray=0.;
 
@@ -395,6 +428,11 @@ namespace stfinv {
 
   /*----------------------------------------------------------------------*/
 
+  /*!
+   * Read out time series data from Mfftengineoutput.
+   * The time series containers in Mfftengineoutput are expected to be larger
+   * than those used for the API of the library (because of padding).
+   */
   void STFFourierDomainEngine::putoutput()
   {
     // scaling factor for source correction filter