changeset 9:3078854c634a

- Renamed DeleteTarget and DeleteAllTargets to RemoveTarget and RemoveAllTargets in Module class
- Added a load of documentation

--- a/doc/dox-mainpage.dox	Thu Feb 18 21:12:41 2010 +0000
+++ b/doc/dox-mainpage.dox	Fri Feb 19 08:51:51 2010 +0000
@@ -1,10 +1,15 @@
 /*!
 \mainpage AIM-C developer documentation
 
+\section intro_sec Introduction
 AIM-C is a real-time version of the the auditory image model (AIM)
 developed at the <a href="http://www.pdn.cam.ac.uk/groups/cnbh/">
 Centre for the Neural Basis of Hearing</a>.
 
+The main development site for AIM-C is at http://aimc.acousticscale.org/. The 
+code is available at http://code.google.com/p/aimc/.
+
+\section design_sec Design
 AIM-C uses a block-based processing scheme. A mono input signal is
 split into short segments, which are sequentially 'pushed' through the
 processing pipeline. The pipeline consists of a number of modules in a
@@ -15,25 +20,21 @@
 segment, or 'frame', of an audio signal with multiple
 channels. Modules generally take a frame (represented as a signal
 bank) as input, and generate zero, one, or more signal bank frames as
-output. Each module is linked to a set of 'target' modules, to which
-they 'push' the frames which they generate. Each of these modules
+output. Each module maintains a list of 'target' modules, to which
+it 'pushes' the frames that it generates. Each module
 performs processing on the output of the previous module, and in turn,
 push the output that they produce to their targets.
 
-This feed-forward, tree-like system allows modules to retain the internal
-state required for processing 
+This feed-forward, tree-like system allows modules to generate as many output
+frames as necessary for each input frame. It also allows for easy 'rewiring'
+of chains of modules. For example, a 'viewer' module could be temporarily 
+added as a target of another module while the user was interested in seeing
+that module's output.
 
+Since each module is an instance of a class, it can retain the necessary state
+variables within the class between calls.
 
-
-
-You can browse the classes using the browser at the left, or
-select a page from the contents below.
-
-
-
-
-
-Coding style
+\section style_sec Coding style
 
 For the most part, AIM-C now follows the <a
 href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">
@@ -43,7 +44,4 @@
 guide.
 
 
-
-
-
 */

--- a/src/Modules/Features/ModuleGaussians.h	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Features/ModuleGaussians.h	Fri Feb 19 08:51:51 2010 +0000
@@ -34,9 +34,6 @@
 #include "Support/Parameters.h"
 #include "Support/SignalBank.h"
 
-/*! \class ModuleGaussians "Modules/Features/ModuleGaussians.h"
- *  \brief
- */
 namespace aimc {
 using std::vector;
 class ModuleGaussians : public Module {

--- a/src/Modules/Output/FileOutputHTK.h	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Output/FileOutputHTK.h	Fri Feb 19 08:51:51 2010 +0000
@@ -18,7 +18,7 @@
 
 /*!
  * \file
- * \brief File output to HTK format class definition
+ * \brief File output to HTK format
  *
  * \author Tom Walters <[e-mail]>
  * \author Willem van Engen <[e-mail]>
@@ -69,13 +69,6 @@
 ((((uint32_t) n) >> 8) & 0x0000FF00) | \
 ((((uint32_t) n) >> 24) & 0x000000FF) )
 
-/*!
- * \class FileOutputHTK "Output/FileOutputHTK.h"
- * \brief File output to HTK class
- *
- * This class gives a method for saving either a signal or a profile to HTK format.
- * \sa Signal, SignalBank
- */
 namespace aimc {
 class FileOutputHTK : public Module {
  public:

--- a/src/Modules/Strobes/ModuleParabola.h	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Strobes/ModuleParabola.h	Fri Feb 19 08:51:51 2010 +0000
@@ -34,10 +34,6 @@
 #include "Support/Parameters.h"
 #include "Support/SignalBank.h"
 
-/*!
- * \class ModuleParabola "Modules/SAI/ModuleParabola.h"
- * \brief SF 2003
- */
 namespace aimc {
 using std::vector;
 class ModuleParabola : public Module {

--- a/src/Support/Module.cc	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/Module.cc	Fri Feb 19 08:51:51 2010 +0000
@@ -109,13 +109,13 @@
   return false;
 }
 
-bool Module::DeleteTarget(Module* target_module) {
+bool Module::RemoveTarget(Module* target_module) {
   if (targets_.erase(target_module) != 0)
     return true;
   return false;
 }
 
-void Module::DeleteAllTargets() {
+void Module::RemoveAllTargets() {
   targets_.clear();
 }
 

--- a/src/Support/Module.h	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/Module.h	Fri Feb 19 08:51:51 2010 +0000
@@ -20,30 +20,6 @@
  *  \brief Base class for all AIM-C modules.
  */
 
-/*! The module construcor is called with a pointer to a set of Parameters.
- * In the constructor, the module sets the defaults for its various
- * parameters.
- * A module is initialized with a pointer to a valid SignalBank
- * (source modules can be initialized with the NULL pointer). After the
- * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
- * returns a pointer to a SignalBank in which the results
- * of the module's processing will be placed. Modules can use the output_
- * SignalBank to store their output, or leave it uninitialized if they do not
- * produce an output.
- * At each call to Process(input), the module takes the
- * SignalBank 'input' (which must, unless otherwise specified, have the same
- * number of channels, sample rate, buffer size and centre frequencies as the
- * SignalBank which was passed to Initialize()), processes it, and places the
- * output in the internal SignalBank output_.
- * Modules can have an arbitrary number of unique targets. Each
- * completed output frame is 'pushed' to all of the targets of the module
- * in turn when PushOutput() is called. To achieve this, after each complete
- * output SignalBank is filled, the module calls the Process() function of
- * each of its targets in turn.
- * When Initialize() is first called. The module Initialize()s all of its
- * targets with its ouptut_ SignalBank, if it's output bank has been set up.
- */
-
 /*! \author: Thomas Walters <[e-mail]>
  *  \date 2010/01/23
  *  \version \$Id: Module.h 4 2010-02-03 18:44:58Z tcw $
@@ -62,54 +38,125 @@
 namespace aimc {
 using std::set;
 using std::string;
+
+/*! \brief Base class for all AIM-C modules.
+ *
+ * Module() is a base class, from which all AIM-C modules are derived. 
+ * Classes deriving from module need to implement, at minimum, the pure
+ * virtual public function Module::Process() and the pure virtual private 
+ * functions Module::InitializeInternal() and Module::ResetInternal().
+ * (Note: this is in contravention of 
+ * <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Inheritance#Inheritance">
+ * this rule on inheritance</a> in the Google style guide, but it is designed 
+ * to make the implementation of modules as simple as possible.)
+ * 
+ * The module constructor is called with a pointer to a set of Parameters.
+ * In the constructor, the module sets the defaults for its various
+ * parameters.
+ * A module is initialized with a reference to a valid SignalBank. After the
+ * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
+ * returns a pointer to a SignalBank in which the results
+ * of the module's processing will be placed. Modules can use the output_
+ * SignalBank to store their output, or leave it uninitialized if they do not
+ * produce an output.
+ * At each call to Process(input), the module takes the
+ * SignalBank 'input' (which must, unless otherwise specified, have the same
+ * number of channels, sample rate, buffer size and centre frequencies as the
+ * SignalBank which was passed to Initialize()), processes it, and places the
+ * output in the internal SignalBank output_.
+ * Modules can have an arbitrary number of unique targets. Each
+ * completed output frame is 'pushed' to all of the targets of the module
+ * in turn when PushOutput() is called. To achieve this, after each complete
+ * output SignalBank is filled, the module calls the Process() function of
+ * each of its targets in turn.
+ * When Initialize() is first called. The module Initialize()s all of its
+ * targets with its ouptut_ SignalBank, if its output bank has been set up.
+ *
+ */
 class Module {
  public:
   explicit Module(Parameters *parameters);
 
   virtual ~Module();
 
-  /* \brief Validate this module's output SignalBank, and initialize
+  /* \brief Initialize the module, including calling InitializeInternal().
+   * Validate this module's output SignalBank, and initialize
    * any targets of the module if necessary.
    * \param input Input SignalBank.
-   * \param output true on success, false on failure.
+   * \return true on success, false on failure.
    *
-   * Note that in most instances when creating a new module, it is better to 
-   * simply implement the pure virtual function InitializeInternal(), rather
-   * than refining a new Initialize. The only reason that Initialize() is made
-   * virtual is to deal with the edge case of input modules which do not take 
-   * a SignalBank as input, but rather generate their own input.
+   * A call to Initialize() will first validate the input SignalBank passed to
+   * it. If this SignalBank is valid, then it will call the
+   * InitializeInternal() function of the child class; this will set up the 
+   * child class, and may, if the module produces an output, initialize the
+   * member variable SignalBank output_. If output_ is initialized after the 
+   * call to InitializeInternal(), the module will Initialize its targets with
+   * the output. In this way, it is possible to initialize an entire module 
+   * tree with a single call to the Initialize() function of the root.
+   *  
+   * This function is declared virtual in order to deal with the edge case of
+   * input modules which do not take a SignalBank as input, but rather
+   * generate their own input. In this case, it is better to be able to
+   * override the default Initialize function. When creating a new module, do
+   * not create a new version of Initialize uness you're sure you know what
+   * you're doing!
    */
   virtual bool Initialize(const SignalBank &input);
 
-  /*! \brief
+  /*! \brief Returns true if the module has been correctly initialized
+   *  \return true if module has been initialized, false otherwise
    */
   bool initialized() const;
 
   /* \brief Add a target to this module. Whenever it generates a new
    * output, this module will push its output to all its targets.
-   * \param input Target module to add.
-   * \param output true on success, false on failure.
+   * \param target_module Pointer to a target Module to add.
+   * \return true on success, false on failure.
+   *
+   * When a pointer is passed as a target to the module, the caller retains
+   * ownership of the module that it points to. The pointed-to module must
+   * continue to exist until it is deleted from the target list by a call
+   * to DeleteTarget() or DeleteAllTargets(), or the current module is
+   * destroyed. Bad things will happen if the Module pointed to is deleted
+   * and Initialize(), Reset() or Process() is subsequently called.
    */
   bool AddTarget(Module* target_module);
 
-  /*! \brief
+  /*! \brief Remove a previously added target module from the list of targets 
+   *  for this module. 
+   *  \param target_module Pointer to the module to remove. This must be a
+   *  pointer that was previously passed to AddTarget() 
+   *  \return true on success, false on failure. 
    */
-  bool DeleteTarget(Module* target_module);
+  bool RemoveTarget(Module* target_module);
 
-  /*! \brief
+  /*! \brief Remove all previously added target modules from the list of
+   *  targets for this module.
    */
-  void DeleteAllTargets();
+  void RemoveAllTargets();
 
-  /*! \brief Process a buffer
+  /*! \brief Process a buffer.
+   * \param input SignalBank of the form which was passed to Initialize()
+   *
+   * Process is called once for each input SignalBank. When implemented in
+   * classes inheriting from aimc::Module, P
+   * this SignalBank contains the (read-only) input to the module. It is
+   * expected that the input SignalBank will have the same number of channels, 
+   * buffer length and sample rate as the SignalBank passed to Initialize. 
    */
   virtual void Process(const SignalBank &input) = 0;
 
   /*! \brief Reset the internal state of this module and all its children to
    *  their initial state.
+   *
+   * Like a call to Initialize() will cause all target modules to be
+   * initialized, a call to Reset() will cause all target modules to be reset. 
    */
   void Reset();
 
-  /*! \brief
+  /*! \brief Return a pointer to the output SignalBank_ for this class.
+   *  \return pointer to the SignalBank that this module uses to store its
+   * output.
    */
   const SignalBank* GetOutputBank() const;
 

--- a/src/Support/StrobeList.h	Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/StrobeList.h	Fri Feb 19 08:51:51 2010 +0000
@@ -20,7 +20,7 @@
  * \file
  * \brief Modifiable List of Strobe Points - helper for SAI generation
  *
- * \author Tom Walters <[e-mail]>
+ * \author Tom Walters <[e-mail]>
  * \date created 2007/08/22
  * \version \$Id: StrobeList.h 1 2010-02-02 11:04:50Z tcw $
  */
@@ -44,11 +44,6 @@
   }
 };
 
-/*!
- * \class Signal "Support/StrobeList.h"
- * \brief Modifiable List of Strobe Points, which must be ordered
- *
- */
 class StrobeList {
  public:
   /*! \brief Create a new strobe list