docu: improve controller interfaces

Author: torbjoernk

include/pfasst/controller/interface.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file controller/interface.hpp
+ * @since v0.1.0
+ */
 #ifndef _PFASST_CONTROLLER_HPP_
 #define _PFASST_CONTROLLER_HPP_
 
@@ -17,39 +21,133 @@ namespace pfasst
    *
    * Base controller (see also SDC, MLSDC, and PFASST controllers).
    *
-   * @tparam time time precision;
-   *     defaults to pfasst::time_precision
+   * @tparam time time precision; defaults to pfasst::time_precision
+   *
+   * @since v0.1.0
+   *
+   * @todo Consider renaming `get_time_step`.
+   *   See [#161](https://github.com/Parallel-in-Time/PFASST/issues/161).
+   *
+   * @ingroup Controllers
    */
   template<typename time = time_precision>
   class Controller
   {
     protected:
       //! @{
+      /**
+       * ordered list of all levels.
+       *
+       * A level is represented by a sweeper implementing the ISweeper interface.
+       *
+       * @note The levels are ordered from coarsest (index `0`) to finest.
+       */
       deque<shared_ptr<ISweeper<time>>>  levels;
+
+      /**
+       * ordered list of transfer operators for levels.
+       *
+       * A transfer operator for a level must implement the ITransfer interface.
+       */
       deque<shared_ptr<ITransfer<time>>> transfer;
       //! @}
 
       //! @{
-      size_t step, iteration, max_iterations;
-      time t, dt, tend;
+      /**
+       * current time step index.
+       */
+      size_t step;
+
+      /**
+       * current iteration index on current time step.
+       */
+      size_t iteration;
+
+      /**
+       * maximum iterations per time step.
+       */
+      size_t max_iterations;
+
+      /**
+       * \\( t_0 \\) of current time step.
+       */
+      time t;
+
+      /**
+       * width of current time step (\\( \\Delta t \\)).
+       */
+      time dt;
+
+      /**
+       * \\( T_{end} \\) of last time step.
+       */
+      time tend;
       //! @}
 
     public:
+      //! @{
       Controller();
       virtual ~Controller();
+      //! @}
 
       //! @{
+      /**
+       * set options from command line etc.
+       *
+       * @param[in] all_sweepers if given also calls ISweeper::set_options for all already added
+       *   levels
+       */
       virtual void set_options(bool all_sweepers = true);
+
+      /**
+       * basic setup routine for this controller.
+       *
+       * @pre It is expected (i.e. the user has to make that sure) that all levels and transfer
+       *   operators have been instantiated and added to this controller before calling
+       *   Controller::setup().
+       */
       virtual void setup();
+
+      /**
+       * set basic time scope of the Controller.
+       *
+       * @param[in] t0     time start point of the first time step
+       * @param[in] tend   time end point of the last time step
+       * @param[in] dt     width of one time step
+       * @param[in] niters maximum number of iterations per time step
+       * The total number of time steps will get computed internally if required.
+       */
       virtual void set_duration(time t0, time tend, time dt, size_t niters);
-      virtual void add_level(shared_ptr<ISweeper<time>> swpr,
-                             shared_ptr<ITransfer<time>> trnsfr = shared_ptr<ITransfer<time>>(nullptr),
+
+      /**
+       * adding a level to the controller.
+       *
+       * @param[in] sweeper  sweeper representing the level
+       * @param[in] transfer corresponding transfer operator for the level
+       * @param[in] coarse   whether to add this level as a coarser one to the list of existing
+       */
+      virtual void add_level(shared_ptr<ISweeper<time>> sweeper,
+                             shared_ptr<ITransfer<time>> transfer = shared_ptr<ITransfer<time>>(nullptr),
                              bool coarse = true);
       //! @}
 
       //! @{
+      /**
+       * total number of levels controlled by this Controller.
+       */
       virtual size_t nlevels();
 
+      /**
+       * get sweeper for level with index @p level.
+       *
+       * @tparam R type of the level sweeper
+       * @returns sweeper of type @p R for requested level
+       *
+       * @internals
+       * @note Asserts sweeper for level @p level can be interpreted as @p R if `NDEBUG` is not 
+       *   defined.
+       * @endinternals
+       */
       template<typename R = ISweeper<time>>
       shared_ptr<R> get_level(size_t level)
       {
@@ -58,18 +156,42 @@ namespace pfasst
         return r;
       }
 
+      /**
+       * get coarsest level.
+       *
+       * @tparam R type of the level sweeper
+       * @see Controller::get_level() with `level=(Controller::nlevels() - 1)`
+       */
       template<typename R = ISweeper<time>>
       shared_ptr<R> get_finest()
       {
         return get_level<R>(nlevels() - 1);
       }
 
+      /**
+       * get coarsest level.
+       *
+       * @tparam R type of the level sweeper
+       * @see Controller::get_level() with `level=0`
+       */
       template<typename R = ISweeper<time>>
       shared_ptr<R> get_coarsest()
       {
         return get_level<R>(0);
       }
 
+      /**
+       * retreive transfer operator for level @p level.
+       *
+       * @tparam R type of the requested transfer operator
+       * @param[in] level level index to retreive transfer operator for
+       * @returns transfer operator of requested type @p R for desired level
+       *
+       * @internals
+       * @note Asserts transfer operator for level @p level can be interpreted as @p R if `NDEBUG`
+       *   is not defined.
+       * @endinternals
+       */
       template<typename R = ITransfer<time>>
       shared_ptr<R> get_transfer(size_t level)
       {
@@ -81,17 +203,75 @@ namespace pfasst
 
       //! @{
       /**
-       * Get current time step number.
+       * get current time step index.
+       *
+       * The time step number is zero-based, i.e. the first time step has index `0`.
+       *
+       * @returns current time step index
        */
       virtual size_t get_step();
+
+      /**
+       * set current time step index.
+       *
+       * @param[in] n index of new time step
+       */
       virtual void   set_step(size_t n);
+
+      /**
+       * get width of current time step.
+       *
+       * @returns \\( \\Delta t \\) of current time step
+       */
       virtual time   get_time_step();
+
+      /**
+       * get start time point of current time step.
+       *
+       * @returns \\( t_0 \\) of current time step
+       */
       virtual time   get_time();
+
+      /**
+       * advance to a following time step
+       *
+       * @param[in] nsteps number of time steps to advance; `1` meaning the next step
+       */
       virtual void   advance_time(size_t nsteps = 1);
+
+      /**
+       * get end time point of last time step.
+       *
+       * @returns \\( T_{end} \\) of last time step.
+       */
       virtual time   get_end_time();
+
+      /**
+       * get current iteration index of current time step.
+       *
+       * @returns current iteration index of current time step.
+       */
       virtual size_t get_iteration();
+
+      /**
+       * set current iteration of current time step.
+       *
+       * @param[in] iter iteration index to set
+       */
       virtual void   set_iteration(size_t iter);
+
+      /**
+       * advance to the next iteration.
+       *
+       * This method may or may not trigger additional post-iteration procedures.
+       */
       virtual void   advance_iteration();
+
+      /**
+       * get maximum number of allowed iterations per time step.
+       *
+       * @returns maximum allowed iterations per time step.
+       */
       virtual size_t get_max_iterations();
       //! @}
 
@@ -103,14 +283,23 @@ namespace pfasst
        * LevelIter::current(), LevelIter::fine() (i.e. `current+1`), and LevelIter::coarse()
        * (`current-1`) sweepers.
        *
-       * Under the hood it satisfies the requirements of std::random_access_iterator_tag, thus
-       * implementing a `RandomAccessIterator`.
+       * @since v0.1.0
+       *
+       * @internals
+       * Under the hood it satisfies the requirements of
+       * [std::random_access_iterator_tag](http://en.cppreference.com/w/cpp/iterator/iterator_tags),
+       * thus implementing a
+       * [RandomAccessIterator](http://en.cppreference.com/w/cpp/concept/RandomAccessIterator).
+       * @endinternals
        */
       class LevelIter
-        : iterator<random_access_iterator_tag, shared_ptr<ISweeper<time>>, int,
-                   ISweeper<time>*, ISweeper<time>>
+        : std::iterator<random_access_iterator_tag, shared_ptr<ISweeper<time>>, int,
+                        ISweeper<time>*, ISweeper<time>>
       {
         protected:
+          /**
+           * Controller this iterator is bound to.
+           */
           Controller* ts;
 
         public:
@@ -131,32 +320,59 @@ namespace pfasst
           //! @}
 
           //! @{
+          /**
+           * get level this iterator is currently pointing at.
+           *
+           * @tparam R type implementing ISweeper
+           * @returns sweeper of type @p R this is currently pointing at
+           */
           template<typename R = ISweeper<time>>
           shared_ptr<R> current()
           {
             return ts->template get_level<R>(level);
           }
 
+          /**
+           * get the next finer level based on LevelIter::current()
+           *
+           * @tparam R type implementing ISweeper
+           * @returns next finer sweeper with respect to current()
+           */
           template<typename R = ISweeper<time>>
           shared_ptr<R> fine()
           {
             return ts->template get_level<R>(level + 1);
           }
 
+          /**
+           * get the next coarser level based on LevelIter::current()
+           *
+           * @tparam R type implementing ISweeper
+           * @returns next coarser sweeper with respect to current()
+           */
           template<typename R = ISweeper<time>>
           shared_ptr<R> coarse()
           {
             return ts->template get_level<R>(level - 1);
           }
 
+          /**
+           * get transfer operator for current level.
+           *
+           * @tparam R type implementing ITransfer
+           * @returns transfer operator for current level
+           */
           template<typename R = ITransfer<time>>
           shared_ptr<R> transfer()
           {
             return ts->template get_transfer<R>(level);
           }
           //! @}
 
-          //! @{
+          /**
+           * @name Standard Operators for Iterators
+           * @{
+           */
           // required by std::iterator
           template<typename R = reference>
           shared_ptr<R> operator*()
@@ -187,7 +403,18 @@ namespace pfasst
       };
 
       //! @{
+      /**
+       * convenience accessor to the finest level.
+       *
+       * @returns iterator to the finest level.
+       */
       virtual LevelIter finest();
+
+      /**
+       * convenience accessor to the coarsest level.
+       *
+       * @returns iterator to the coarsest level.
+       */
       virtual LevelIter coarsest();
       //! @}
   };