Doxygen: fill in missing file level headlines for Proc-Layer (Player)

src/proc/play/dummy-play-connection.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file dummy-play-connection.cpp
- ** TODO dummy-play-connection.cpp
+ ** Implementation of a service for mock render playback to support testing.
  */
 
 

src/proc/play/dummy-play-connection.hpp

@@ -21,7 +21,7 @@
 */
 
 /** @file dummy-play-connection.hpp
- ** Dummy and test setup of playback and rendering, \em omitting most of the Lumiera engine.
+ ** Dummy and test setup of playback and rendering, _omitting most_ of the Lumiera engine.
  ** Building this dummy configuration was driven by the need to test and verify the design
  ** in the course of building the foundations of the render engine. The design of Lumiera's
  ** engine is elaborate, and thus -- for a long time -- we have to live with a not-yet
@@ -32,7 +32,7 @@
  ** these placeholders are connected, allowing to produce specific test situations and then
  ** verify the results after the test run.
  ** 
- ** \par Use cases
+ ** # Use cases
  ** This dummy setup can be used in various circumstances
  ** - for unit tests we want to produce artificial test media frames: each TestFrame is
  **   produced with a reproducible pseudo-random sequence and can be verified to the last bit.
@@ -44,16 +44,16 @@
  **   to verify a more complicated wiring setup. Thus, the DummyPlayConnection is there to stay!
  ** 
  ** Because these are somewhat similar usage scenarios, where this and that part is to be exchanged
- ** for some, we prefer a <i>policy based design</i> here: The DummyPlayConnection is templated
- ** to use a \em strategy, filling in the variable parts.  
+ ** for some, we prefer a _policy based design_ here: The DummyPlayConnection is templated
+ ** to use _a strategy,_ filling in the variable parts.
  ** 
- ** \par provided test services
+ ** # provided test services
  ** By using different strategy template parameters, we create different flavours of the dummy;
  ** each one counting as a separate setup (not related to each other, that is). The actual instance
  ** then can just be default created; it should be placed into an scope enduring the whole usage
  ** cycle. Repeated re-initialisation or re-loading is outside the intended usage scope here.
  ** 
- ** The <b>core interface</b> allows to retrieve dummy implementations of
+ ** The *core interface* allows to retrieve dummy implementations of
  ** - a session model exposing exit node(s)
  ** - generator object(s) to live within this session model
  ** - corresponding generator nodes to serve as implementation of the former
@@ -61,9 +61,9 @@
  ** - OutputSlot implementations to serve as pseudo- or demo output facilities
  ** - an OutputManager exposing those output facilities.
  ** 
- ** The <b>test support interface</b> provides a test driver for performing a controlled 
+ ** The *test support interface* provides a test driver for performing a controlled
  ** playback or rendering for some time. Thus, a test routine may lock into a blocking wait,
- ** to investigate results after the planned test sequence was performed. 
+ ** to investigate results after the planned test sequence was performed.
  ** 
  ** @see lumiera::DummyPlayer
  ** @see gui::PlaybackController usage example 
@@ -129,10 +129,10 @@ namespace play {
 //  using lib::ScopedCollection;
 //  using lib::Literal;
     using lib::eachEntry;
-  
+    
     typedef asset::ID<Pipe> PID;
     typedef asset::ID<Struct> TID;
-      
+    
 //  typedef ModelPortRegistry::ModelPortDescriptor const& MPDescriptor;
     
     
@@ -153,7 +153,7 @@ namespace play {
     const string namePortB("bus-B");
     
     /** 
-     * helper for dummy render engine: 
+     * helper for dummy render engine:
      * Simulate the result of a build process,
      * without actually running the builder.
      * Produces some mock pipes, model ports etc.
@@ -208,7 +208,7 @@ namespace play {
           }
       };
   }
-
+  
   
   /****************************************************************//**
    * Framework for dummy playback and rendering.
@@ -216,7 +216,7 @@ namespace play {
    * allowing to start a data producing process while leaving out
    * various parts of the real engine implementation. The specific
    * mode of operation, suitable for various test scenarios, may be
-   * fine tuned by the strategy object defined as template parameter. 
+   * fine tuned by the strategy object defined as template parameter.
    */
   template<class DEF>
   class DummyPlayConnection
@@ -274,4 +274,4 @@ namespace play {
   
   
 }} // namespace proc::play
-#endif
+#endif /*PROC_PLAY_DUMMY_PLAY_CONNECTION_H*/

src/proc/play/dummy-player-service.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file dummy-player-service.cpp
- ** TODO dummy-player-service.cpp
+ ** Implementation of a service for mock render output to support testing.
  */
 
 

src/proc/play/output-director.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file output-director.cpp
- ** TODO output-director.cpp
+ ** Implementation of global output connection management
  */
 
 

src/proc/play/output-slot.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file output-slot.cpp
- ** TODO output-slot.cpp
+ ** Generic implementation functionality common to all output connections.
  */
 
 

src/proc/play/output-slot.hpp

@@ -32,7 +32,7 @@
  ** external output, or a group of such outputs (e.g. left and right sound card output channels),
  ** or an output file or similar capability accepting media content. Initially, an output slot
  ** needs to be provided, configured and registered, using an implementation suitable for the
- ** kind of media data to be output (sound, video) and also suitable for the special circumstances
+ ** kind of media data to be sent (sound, video) and also suitable for the special circumstances
  ** of the output capability (render a file, display video in a GUI widget, send video to some
  ** full screen display, establish a Jack port, just use some kind of "sound out"). An output
  ** slot is always limited to a single kind of media, and to a single connection unit, but
@@ -43,16 +43,16 @@
  ** there may be only a single client using a given output slot this way. To stress this point:
  ** output slots don't provide any kind of inherent mixing capability; any adaptation, mixing,
  ** overlaying and sharing needs to be done within the nodes network producing the output data
- ** to be fed into the slot. (in special cases, some external output capabilities — e.g. the
- ** Jack audio connection system — may still provide additional mixing capabilities,
+ ** to be fed into the slot. (in special cases, some external output capabilities -- e.g. the
+ ** Jack audio connection system -- may still provide additional mixing capabilities,
  ** but that's beyond the scope of the Lumiera application)
  ** 
  ** Once allocated, the output slot returns a set of concrete sink handles (one for each
  ** physical channel expecting data). The calculating process feeds its results into those handles.
  ** Size and other characteristics of the data frames are assumed to be suitable, which typically
  ** won't be verified at that level anymore. Besides that, the allocation of an output slot reveals
- ** detailed timing expectations. The client is required to comply to these timings when \em emitting
- ** data — he's even required to provide a current time specification, alongside with the data.
+ ** detailed timing expectations. The client is required to comply to these timings when _emitting_
+ ** data -- he's even required to provide a current time specification, alongside with the data.
  ** Based on this information, the output slot has the ability to handle timing failures gracefully;
  ** the concrete output slot implementation is expected to provide some kind of de-click or
  ** de-flicker facility, which kicks in automatically when a timing failure is detected.

src/proc/play/play-process.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file play-process.cpp
- ** TODO play-process.cpp
+ ** Implementation to organise an ongoing playback/rendering process
  */
 
 

src/proc/play/play-service.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file play-service.cpp
- ** TODO play-service.cpp
+ ** Implementation of core parts of the Player subsystem
  */
 
 

src/proc/play/play-service.hpp

@@ -30,12 +30,12 @@
  ** of the High-Level-Model). These model ports are the (side effect) result of a
  ** build process performed on the High-Level-Model, causing all nominal output
  ** designations within the model to be resolved as far as possible. Additionally,
- ** for \em playback, the global level of the model (the global pipes of a timeline)
+ ** for _playback,_ the global level of the model (the global pipes of a timeline)
  ** need to be connected to a viewer component. This results in a further resolution
  ** step, mapping the output designations to the concrete output possibilities of
  ** the running Lumiera instance. This mapping information is kept embedded within
  ** an OutputManager instance, passed as parameter when invoking the player service.
- ** Alternatively, for \em rendering, a similar kind of output mapping information
+ ** Alternatively, for _rendering,_ a similar kind of output mapping information
  ** needs to be provided, again embedded within an OutputManager instance, this
  ** time leading to an output file to be rendered.
  ** 
@@ -46,7 +46,8 @@
  ** the scenes the corresponding PlayProcess gets terminated and prepared for cleanup. 
  ** 
  ** @see engine::EngineService
- ** @todo WIP-WIP-WIP as of Nov.2011
+ ** @todo started as draft in 11/2011
+ ** @todo as of 2016 development in this area is stalled, but the design done thus far valid
  ** 
  */
 

src/proc/play/render-configurator.cpp

@@ -22,7 +22,9 @@
 
 
 /** @file render-configurator.cpp
- ** TODO render-configurator.cpp
+ ** Implementation functionality to bridge between engine::PlayService and engine::EngineService.
+ ** The former allows to start playback (or rendering) as a high-level activity, while the latter
+ ** can manage and perform [calculation streams](\ref CalcStream)
  */
 
 

src/proc/play/render-configurator.hpp

@@ -21,7 +21,7 @@
 */
 
 /** @file render-configurator.hpp
- ** Strategy holding all the detail knowledge necessary to establish
+ ** Strategy to hold all the detail knowledge necessary to establish
  ** a running render CalculationStream. 
  ** 
  ** @see engine::EngineService

src/proc/play/sound/jack-output.cpp

@@ -22,7 +22,9 @@
 
 
 /** @file jack-output.cpp
- ** TODO jack-output.cpp
+ ** 
+ ** @todo empty placeholder: yes we will support Jack Audio!
+ ** 
  */
 
 

src/proc/play/sound/jack-output.hpp

@@ -21,7 +21,9 @@
 */
 
 /** @file jack-output.hpp
- **
+ ** 
+ ** @todo empty placeholder to underpin the claim: yes we will support Jack Audio!
+ ** 
  ** @see lumiera::Display
  ** @see lumiera::DummyPlayer
  ** @see gui::PlaybackController usage example 

src/proc/play/timings.cpp

@@ -22,7 +22,11 @@
 
 
 /** @file timings.cpp
- ** TODO timings.cpp
+ ** Implementation of a data tuple for timing specification.
+ ** A Timings record represents a constraint on playback, and will be
+ ** used to organise and the calculations necessary to generate the data.
+ ** Especially, a Timings record serves to establish a relation to an externally
+ ** fixed time grid or time source.
  */