[doc] Improve documentation.

Author: olivier-stasse

doc/additionalDoc/dgshell_doc.h

@@ -1,5 +1,5 @@
 /**
-
+\ingroup gshellfunctions
 \page dgshell_doc dg-shell executable
 The dynamic-graph shell program "dg-shell" allows access to the dynamic-graph library's
 Interpreter class, which can execute commands and scripts from the command line.

doc/additionalDoc/package.h

@@ -22,31 +22,100 @@
 /**
 \mainpage
 
+
+
 \section intro_dynamicGraph Introduction
 
 The dynamic-graph package is used to connect computation nodes, "entities"
-together using a graph system, akin to what Simulink does. With the building
-blocks this package provides, you can easily create a full computation graph
+together using a graph system, akin to what Simulink does. Entities are connected
+through input and output signals.
+With the building blocks this package provides, you can easily create a full computation graph
 for a given problem. It is the basis for the stack of tasks operation.
 
-\image html entity.png
-Functionality:
-\li Built-in scripting language* for fast prototyping and testing
+
+\subsection controlgraph Exemple: Real-time control
+
+<p>To give a more concrete example, the real-time control used by the Gepetto group for the humanoid robot HRP-2
+is detailled.</p>
+<p>
+Real-time control system are usually driven by a cyclic computational node which 
+needs to send a control reference value to each motors of a robot. To compute this
+control reference values, sensor values need to be provided.
+In the Stack-Of-Tasks special entities called Device are used to
+provide an abstract interface to the hardware.</p>
+A scheme of the real-time control graph used for the humanoid robot HRP-2 is depicted in the following figure:
+
+\image html Concept-Software-Fig.png
+
+<p>The device therefore has a specific input which should contain the control vector.
+This control vector is the result of a computation solving a control problem.
+The entity in charge of solving this control problem is called "Solver" in the previous
+figure.
+In the SoT framework it is often cast as an optimization problem.
+This optimization problem is build using a control "Task" (not to be confused with the 
+general word task). A control "Task" regulates the difference with a "Feature" computed
+on the current robot state and a "Desired Feature". For instance when walking, the regulated
+feature is the robot's Center-Of-Mass (CoM) position. The "Feature" is computed using a 
+library using the robot model and the sensor value. The entity making this computation is "Dyn".
+A walking pattern generator using foot-steps position given in advance generates the desired
+value for the CoM. 
+Note that the "Dyn" entity uses the sensor provided by the entity "Robot". </p>
+
+<p>
+From a pure computer science viewpoint we wish to avoid recomputing data such as articular Jacobians
+when this is unnecessary. Therefore the data generated by an entity through signals may have two types of
+dependencies: one dependency related to time and dependencies on other signals. Internally an entity
+does not recompute the data if no new information is available, it is simply providing the same information
+computed before. Please note that this package provides only the computational framework to realize
+the data dependency and the entities. Solvers, libraries to compute mechanical quantities are provided
+in different packages.
+</p>
+
+<p>
+Finally in order to dynamically create a graph, it is possible \b on-line to load classes of entities  and
+create instances of entities.</p>
+
+\subsection Functionnalities
+
+\li Built-in scripting language* for fast prototyping and testing of computational graph
 \li Support for extensions and modules using dynamic link libraries
 \li Template-based signal definition, independent
 \li Type-safe connection of input and output signals
 \li On-demand signal computation as well as a caching system for signal values allow fast
 computation of signal values, which is a critical point for real-time systems\n
 See \ref scriptingabout
 
-\section overview Code overview
-This code implements the factory design pattern, making creation of entities
-(as C++ classes) available to packages depending on the dynamic-graph API.
-For more information on this package's code or how to develop your own entities,
-see \ref usecase.
+\section entity Computational Entity
+\image html entity.png
+
+\subsection entity_definition General definition
+Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
+The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$) 
+and should have a minimal computational time foot-print.
+
+For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
+To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
+to get the needed data.
+It might be provided by the connection with remote computers through a middleware, or specific protocols,
+but in general the external data is based upon the sensor values provided by a "Device" entity.
+For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
+signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
+
+To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity 
+or get information from the entity.
+As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
+executed in a \b none-real-time thread.
+
+\subsection entity_classes Entity class
+Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
+It is therefore necessary to specify the location of their dynamical libraries.
+However given the time it might take to load the library, it is not advised to do that during a control-law computation.
+Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
 
+The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
+check the install log or the CMakeLists.txt file to check the installation path).
 
-\section entities List of entities in this package
+\subsection entities List of entities in this package
 Since most of the functionality in projects using the dynamic-graph framework
 is exposed from entities, here is a short description of all the entities contained in
 this package. Note that most entities are contained in a binary file that closely matches
@@ -57,42 +126,46 @@ enable creation of this entity through the factory.
 \li ShellProcedure
 \li \ref shellfunctions_doc
 
-The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
-check the install log or the CMakeLists.txt file to check the installation path).
-\section sigintro About signals
+\subsection specific_semantics Specific semantics with entities
+
+It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
+\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
+\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
+\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
+
+\section sigintro Signals
 
 Entities can output different types of signals. All signals are templated by a Time
 tick type parameter (which is used in the caching of signals) - usually \c int. Signals
 are also templated after the type of data they accept or provide. For example:
 (example)
 For a more detailed programmer-oriented description of signals, please see \ref signals
 
-\section scriptingabout Notes about the scripting language
-The scripting language allows entities to define their own commands, and
-provides a basic framework for working with the dynamic-graph.
-At the time of writing, there is talk about replacing (or complementing) this limited
-language with a python interpreter.
+\section graph Graph
 
-A couple of functions are built-in in the interpreter and provides low-level features such as file sourcing or
-plug-in loading.\n
-These functions are:\n
-\code plug <obj1.sig1> <obj2.sig2> \endcode plugs the signal sig1 of obj1 to the signal sig2 of obj2. sig1 and sig2
-have to be of the same type. sig1 has to be an output signal and sig2 an input signal.
-\code new <class> <object> \endcode instantiates an object object of class class. object has to be a free identifier and
-class an existing entity.
-\code destroy <object> \endcode deletes an instance previously created.
-\code run <script.txt> \endcode sources (i.e. read and interpret) an external file.
-\code loadPlugin <file.so> <directory> \endcode loads a plugin called file.so and located in the directory directory.
-\code unloadPlugin <path/file.so> \endcode unloads a plugin.
-\code help \endcode lists available functions.
-\code set <obj.signal> <value> \endcode defines an input signal to a specific, constant, value.
-\code get <obj.signal> <value> \endcode prints out a signal value.
-\code compute <obj.sig> <time> \endcode computes an output signal and sets the associated time to time.
+In this package, the graph considered are directed graphs.
+
+\subsection factory Factory
+
+The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
+
+\subsection pool Pool
+The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
+The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
+from the entities. Signals are the directed edges of the graph. 
+The pool can write a file representing the graph of entities. 
+
+\subsection scriptingabout Building the graph 
+
+This package provides a scripting language allows entities to define their own commands, and
+provides a basic framework to build dynamically the computational graph.
+However bindings have been created with python in the <a href="https://github.com/stack-of-tasks/dynamic-graph-python">dynamic-graph-python package</a>
+and we strongly recommend to use this package instead of the in-house scripting language.
 
 \section usecase How to use this package
-1) Programmatically\n
+\subsection use_programmtically Programmatically
 Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
- declared within the code and compiled to shared libraries (.so/.dll files).
+declared within the code and compiled to shared libraries (.so/.dll files).
 These libraries can be loaded at run-time using the PluginLoader methods,
 and at the same time register their class names to the Factory (see the
 examples in the SOT documentation to learn how).
@@ -112,28 +185,54 @@ Some basic shell functions, and support for procedures, are also included.
 For a complete list of those, load the plugin shell-functions.so and type 'help'
 at the command line.
 
-The (singletons made available by including the corresponding headers in this
+The singletons made available by including the corresponding headers in this
 module are:
 \li dynamicgraph::FactoryStorage
 \li dynamicgraph::PoolStorage
 
 For an example of a program creating entities in C++, see the unit test
 test_pool.cpp (in your package source directory/unitTesting).
 
-2) Through scripts\n
+\subsection use_scripts Through scripts
 The program \ref dgshell_doc can be used to have scripting access to the dynamic-graph
 library, where you can execute scripts and commands, load plugins, create entities and connect signals.
 
 Here is a typical use case for programmers:
 \image html figures/use-case.png
 
-\section References
+\section references References
+\anchor Mansard2009
+
+<b> "A versatile Generalized Inverted Kinematics implementation for collaborative working humanoid robots: The Stack Of Tasks"</b>,
+<em>N. Mansard, O. Stasse, P. Evrard, A. Kheddar,</em>
+Int. Conf. on Autonomous Robots, ICAR, 2009
+
 \anchor Mansard2007
 
 <b>"Task sequencing for sensor-based control"</b>,
 <em>N. Mansard, F. Chaumette,</em>
 IEEE Trans. on Robotics, 23(1):60-72, February 2007
 
+\namespace dynamicgraph This is the namespace where every object and class of this library is located.
+
+\defgroup gshellfunctions Notes about the scripting language
+@{
+A couple of functions are built-in in the interpreter and provides low-level features such as file sourcing or
+plug-in loading.\n
+These functions are:\n
+\code plug <obj1.sig1> <obj2.sig2> \endcode plugs the signal sig1 of obj1 to the signal sig2 of obj2. sig1 and sig2
+have to be of the same type. sig1 has to be an output signal and sig2 an input signal.
+\code new <class> <object> \endcode instantiates an object object of class class. object has to be a free identifier and
+class an existing entity.
+\code destroy <object> \endcode deletes an instance previously created.
+\code run <script.txt> \endcode sources (i.e. read and interpret) an external file.
+\code loadPlugin <file.so> <directory> \endcode loads a plugin called file.so and located in the directory directory.
+\code unloadPlugin <path/file.so> \endcode unloads a plugin.
+\code help \endcode lists available functions.
+\code set <obj.signal> <value> \endcode defines an input signal to a specific, constant, value.
+\code get <obj.signal> <value> \endcode prints out a signal value.
+\code compute <obj.sig> <time> \endcode computes an output signal and sets the associated time to time.
+@}
 
 \defgroup dgraph Core classes and objects
 @{
@@ -180,5 +279,4 @@ computations, when accessed.
 
 @}
 
-\namespace dynamicgraph This is the namespace where every object and class of this library is located.
 */

doc/additionalDoc/shellfunctions_doc.h

@@ -1,4 +1,5 @@
 /**
+\ingroup gshellfunctions
 \page shellfunctions_doc ShellFunctions
 \note Note: this documentation covers specific aspects of the in-house
 scripting language currently used by the dynamic-graph script. Unless