Merge branch 'master' of github.com:jrl-umi3218/dynamic-graph into topic/submodule

doc/additionalDoc/dgshell_doc.h

@@ -9,6 +9,6 @@ There is also a linux shell script available, dg-shell-plugin, that creates a
 and loads a default script whose goal is to load useful plugins at startup
 (shell-functions and shell-procedure).
 
-For an example of shell commands and scripts, see \ref scriptingabout .
+For an example of shell commands and scripts, see \ref scriptingabout.
 
 **/

doc/additionalDoc/package.h

@@ -149,10 +149,10 @@ Classes, entities and binaries that make up the core of the dynamic-graph librar
 This part provides the mechanism to transfer information
 from one entity to another. There are three main types of signals,
 all deriving from the common class dynamicgraph::SignalBase :
-\li dynamicgraph::Signal : a "normal" signal, passing data around \bby \bvalue
+\li dynamicgraph::Signal : a "normal" signal, passing data around \b by \b value
 \li dynamicgraph::SignalPtr : a signal used for efficient passing of large data, by reference (or rather, C pointers)*
 \li dynamicgraph::SignalTimeDependent : a signal that enforces a time dependency between other signals,
-making sure its inputs are up to date, using a incrementing time tick as reference.
+making sure its inputs are up to date on access, using a incrementing time tick as reference.
 
 \n* Note: this may cause a problem if this package is used in a multithreaded program.
 
@@ -160,13 +160,18 @@ Signals can be grouped together using dynamicgraph::SignalArray.
 
 Signals implement a caching mechanism by storing the last computation time tick.
 
-Signals can be plugged ("plug" script command) into one another or set through shell commands.
-\section samp Samples
+Some signals can be plugged ("plug" script command) into one another or set through shell commands.
+
+For more information, please see the individual signal pages.
+
+\b Samples
+
+\li The following code ensures the jacobian output signal uses up-to-date values for its
+computations, when accessed.
 
-\li The following code ensures the jacobian uses a
 \code
-  //! \brief This signal returns the Jacobian of the current value
-  //  according to the robot state: \f$ J(t) = \frac{\delta{\bf s}^*(t)}{\delta {\bf q}(t)}\f$ 
+  // This signal returns the Jacobian of the current value
+  //  according to the robot state
   dg::SignalTimeDependent<ml::Matrix,int> jacobianSOUT;
 
   (...)

doc/additionalDoc/tracerdoc.h

 /**
 \page tracerdoc Tracer
 \section description Description
-The \b Tracer entity monitors a set of signals. With an input change on the entity's <trigger> signal,
+The \b Tracer entity monitors a set of signals. With an input change on the entity's [trigger] signal,
 the tracked signal values are recorded and traced to a file. The behavior of the trace-to-file
 function can be changed, from printing to a file immediately after recording, to printing out
 only when asked explicitly.

include/dynamic-graph/interpreter-helper.h

@@ -79,7 +79,7 @@ class DYNAMICGRAPH_EXPORT InterpreterHelper
   /*! \name Implements the commands.
     @{
    */
-  /*! \brief Instanciante an object
+  /*! \brief Instanciate an object
     Extracts the name and the class of the object, verifies it is unique,
     and creates the instance if this is the case.
    */
@@ -96,8 +96,11 @@ class DYNAMICGRAPH_EXPORT InterpreterHelper
   /*! \brief Connect two signals.
     Connect the input signal obj1.signame1 to the output signal
     obj2.signame2.
-    \param[in] obj1.signame1: the input signal.
-    \param[in] obj2.signame2: the output signal.
+    \param[in] obj1  The input object.
+    \param[in] obj2  The output object.
+    \param[in] signame1 The input object's signal name
+    \param[in] signame2 The output object's signal name
+    \param[out] os The output stream for logging and error output
   */
   void cmdPlug( const std::string& obj1, const std::string & signame1,
 		const std::string& obj2, const std::string & signame2,
@@ -117,23 +120,23 @@ class DYNAMICGRAPH_EXPORT InterpreterHelper
   void cmdUnloadPlugin( const std::string& pluginName,
 			std::ostream& os );
 
-  /*! \brief Set a signal <obj.signal> to a value <value>
-    with cmdArg = "<obj.signal> <value>"
+  /*! \brief Set a signal [obj.signal] to a value [value]
+    with cmdArg = "[obj.signal] [value]"
    */
   void cmdSetSignal( const std::string& objname,
 		     const std::string& signame,
 		     const std::string& cmdArg,
 		     std::ostream& os);
 
-  /*! \brief Display the value of the signal <obj.signal>
-    with cmdArg = "<obj.signal>"
+  /*! \brief Display the value of the signal [obj.signal]
+    with cmdArg = "[obj.signal]"
    */
   void cmdGetSignal( const std::string& objname,
 		     const std::string& signame,
 		     std::ostream& os);
 
-  /*! \brief Compute the value of the signal <obj.signal> at time <time>
-    with cmdArg = "<obj.signal> <time>"
+  /*! \brief Compute the value of the signal [signame=obj.signal] at time [time]
+    with cmdArg = "[obj.signal] [time]"
    */
   void cmdComputeSignal( const std::string& objname,
 			 const std::string& signame,

include/dynamic-graph/interpreter.h

@@ -142,18 +142,18 @@ class DYNAMICGRAPH_EXPORT Interpreter
   /*! \brief Run a script */
   void cmdRun( const std::string& cmdLine, std::istringstream& cmdArg, std::ostream& os );
 
-  /*! \brief Set a signal <obj.signal> to a value <value>
-    with cmdArg = "<obj.signal> <value>"
+  /*! \brief Set a signal [obj.signal] to a value [value]
+    with cmdArg = "[obj.signal] [value]"
    */
   void cmdSetSignal( const std::string& cmdLine, std::istringstream& cmdArg, std::ostream& os );
 
-  /*! \brief Display the value of the signal <obj.signal>
-    with cmdArg = "<obj.signal>"
+  /*! \brief Display the value of the signal [obj.signal]
+    with cmdArg = "[obj.signal]"
    */
   void cmdGetSignal( const std::string& cmdLine, std::istringstream& cmdArg, std::ostream& os );
 
-  /*! \brief Compute the value of the signal <obj.signal> at time <time>
-    with cmdArg = "<obj.signal> <time>"
+  /*! \brief Compute the value of the signal [obj.signal] at time [time]
+    with cmdArg = "[obj.signal] [time]"
    */
   void cmdComputeSignal( const std::string& cmdLine, std::istringstream& cmdArg, std::ostream& os );
 

include/dynamic-graph/pool.h

@@ -120,8 +120,8 @@ class DYNAMICGRAPH_EXPORT PoolStorage
     If the method of the object displays some information this will
     be done on os.
 
-    The commands specific to the <b>g_pool<\b> object are:
-    \li <b>list</b> : List all the entities registered in the g_pool.s
+    The commands specific to the \b g_pool object are:
+    \li \b list : List all the entities registered in the pool
   */
   void commandLine( const std::string& objectName,const std::string& functionName,
 		    std::istringstream& cmdArg, std::ostream& os );

include/dynamic-graph/signal-base.h

@@ -30,6 +30,11 @@
 
 namespace dynamicgraph {
 
+/** \brief The base class for signals: not to be used as such.
+ Signal values can be accessed programmatically using the access() or accessCopy()
+ methods; the former directly accesses the value of the signal, which can involve an
+ extra computation, while the latter accesses a cached value, or 'copy'.
+ */
 template< class Time >
 class SignalBase : public boost::noncopyable
 {
@@ -108,6 +113,7 @@ class SignalBase : public boost::noncopyable
   /* --- SET ---------------------------------------------------------------- */
 
   /* Generic set function. Should be reimplemented by the specific Signal.
+   * Sets a signal value
    */
   virtual void set( std::istringstream& value )
       { DG_THROW ExceptionSignal( ExceptionSignal::SET_IMPOSSIBLE,

include/dynamic-graph/signal-ptr.h

@@ -28,6 +28,10 @@
 
 namespace dynamicgraph {
 
+/** \brief This is the only type of signal that can be plugged to, using the plug() command.
+ In that sense, when plugged into, it acts as a "pointer" to the input signal, hence
+ the name. Operator -> is also overloaded and can be used to access the pointed signal.
+ */
 template< class T,class Time >
 class SignalPtr
 : public virtual Signal<T,Time>
@@ -79,7 +83,7 @@ class SignalPtr
     virtual std::ostream& writeGraph(std::ostream& os) const;
     virtual std::ostream& display( std::ostream& os ) const;
 
-    /* For compatibility, .access() is equivalent to ->access(). For explicite
+    /* For compatibility, .access() is equivalent to ->access(). For explicit
      * pointer dereference :
      * Prefere ->() to ()
      */

include/dynamic-graph/signal-time-dependent.h

@@ -27,6 +27,14 @@
 
 namespace dynamicgraph {
 
+/*!  \brief A type of signal that enforces a time dependency between other signals,
+making sure its inputs are up to date on access, using a incrementing time tick as reference.
+It works this way: for a given SignalTimeDependent S, the user manually adds dependent signals through the
+use of the addDependency function. On access (calling the signal S operator () or access(Time) function),
+if the dependent signals are not up-to-date, i.e. if their [last update] time is less than the
+current time, their value will be access()'ed to bring them up-to-date. Thus, the value of dependent
+signals can be accessed \b quickly and \b repeatedly through the accessCopy() function.
+ */
 template< class T,class Time >
 class SignalTimeDependent
 : public virtual Signal<T,Time>

include/dynamic-graph/signal.h

@@ -43,6 +43,13 @@ namespace dynamicgraph {
   or evaluated as a function.
   See SignalPtr and SignalTimeDependent for other types of signals,
   and SignalArray for a way of grouping them.
+
+  There are several ways to specify the value output by a signal:
+  \li using the function setConstant(T) to set the value of the signal to T;
+  \li using the function setReference(mutex, T*) to set the value from a pointer,
+  whose access is restricted by a mutex;
+  \li using the function setFunction(boost::function2) that will be called when the
+  signal's value is accessed.
  */
 template< class T,class Time >
 class Signal

include/dynamic-graph/time-dependency.h

@@ -29,7 +29,8 @@
 
 namespace dynamicgraph {
 
-
+/** \brief A helper class for setting and specifying dependencies between signals.
+ */
 template< class Time >
 class TimeDependency
 {