From 8fc8900c60892e8060c2f0868e6333cea7a4054f Mon Sep 17 00:00:00 2001
From: Francois Bleibel <fbleibel@gmail.com>
Date: Mon, 1 Nov 2010 17:03:52 +0900
Subject: [PATCH] Corrected doxygen errors. Complemented documentation on
signals.
---
doc/additionalDoc/dgshell_doc.h | 2 +-
doc/additionalDoc/package.h | 19 ++++++++++-------
doc/additionalDoc/tracerdoc.h | 2 +-
include/dynamic-graph/interpreter-helper.h | 21 +++++++++++--------
include/dynamic-graph/interpreter.h | 12 +++++------
include/dynamic-graph/pool.h | 4 ++--
include/dynamic-graph/signal-base.h | 6 ++++++
include/dynamic-graph/signal-ptr.h | 6 +++++-
include/dynamic-graph/signal-time-dependent.h | 8 +++++++
include/dynamic-graph/signal.h | 7 +++++++
include/dynamic-graph/time-dependency.h | 3 ++-
11 files changed, 62 insertions(+), 28 deletions(-)
diff --git a/doc/additionalDoc/dgshell_doc.h b/doc/additionalDoc/dgshell_doc.h
index 81ba8bf..dc6f58a 100644
--- a/doc/additionalDoc/dgshell_doc.h
+++ b/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.
**/
diff --git a/doc/additionalDoc/package.h b/doc/additionalDoc/package.h
index 113d938..d545d8b 100644
--- a/doc/additionalDoc/package.h
+++ b/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;
(...)
diff --git a/doc/additionalDoc/tracerdoc.h b/doc/additionalDoc/tracerdoc.h
index fa09d4e..ca408e7 100644
--- a/doc/additionalDoc/tracerdoc.h
+++ b/doc/additionalDoc/tracerdoc.h
@@ -1,7 +1,7 @@
/**
\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.
diff --git a/include/dynamic-graph/interpreter-helper.h b/include/dynamic-graph/interpreter-helper.h
index bfa9e3c..04dd613 100644
--- a/include/dynamic-graph/interpreter-helper.h
+++ b/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,
diff --git a/include/dynamic-graph/interpreter.h b/include/dynamic-graph/interpreter.h
index d7ea968..798d709 100644
--- a/include/dynamic-graph/interpreter.h
+++ b/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 );
diff --git a/include/dynamic-graph/pool.h b/include/dynamic-graph/pool.h
index eda72bf..0c4daac 100644
--- a/include/dynamic-graph/pool.h
+++ b/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 );
diff --git a/include/dynamic-graph/signal-base.h b/include/dynamic-graph/signal-base.h
index a9c5e88..843dc92 100644
--- a/include/dynamic-graph/signal-base.h
+++ b/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,
diff --git a/include/dynamic-graph/signal-ptr.h b/include/dynamic-graph/signal-ptr.h
index 7ca8c53..45d89f3 100644
--- a/include/dynamic-graph/signal-ptr.h
+++ b/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 ()
*/
diff --git a/include/dynamic-graph/signal-time-dependent.h b/include/dynamic-graph/signal-time-dependent.h
index f582586..f17337b 100644
--- a/include/dynamic-graph/signal-time-dependent.h
+++ b/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>
diff --git a/include/dynamic-graph/signal.h b/include/dynamic-graph/signal.h
index b974c38..07ed582 100644
--- a/include/dynamic-graph/signal.h
+++ b/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
diff --git a/include/dynamic-graph/time-dependency.h b/include/dynamic-graph/time-dependency.h
index d5f38ef..2369cbd 100644
--- a/include/dynamic-graph/time-dependency.h
+++ b/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
{
--
GitLab