Commit 8fc8900c authored by Francois Bleibel's avatar Francois Bleibel
Browse files

Corrected doxygen errors. Complemented documentation on signals.

parent 54e5e6e1
......@@ -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.
**/
......@@ -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;
(...)
......
/**
\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.
......
......@@ -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,
......
......@@ -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 );
......
......@@ -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 );
......
......@@ -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,
......
......@@ -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 ()
*/
......
......@@ -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>
......
......@@ -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
......
......@@ -29,7 +29,8 @@
namespace dynamicgraph {
/** \brief A helper class for setting and specifying dependencies between signals.
*/
template< class Time >
class TimeDependency
{
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment