Commit 8be0de7e authored by Olivier Stasse's avatar Olivier Stasse Committed by olivier stasse
Browse files

[doc] Improve documentation style + text on Command, Entity and Value classes

parent 75fe2b44
...@@ -14,7 +14,11 @@ OPTION(SUFFIX_SO_VERSION "Suffix library name with its version" ON) ...@@ -14,7 +14,11 @@ OPTION(SUFFIX_SO_VERSION "Suffix library name with its version" ON)
SET(PROJECT_USE_CMAKE_EXPORT TRUE) SET(PROJECT_USE_CMAKE_EXPORT TRUE)
SET(CUSTOM_HEADER_DIR ${PROJECT_NAME}) SET(CUSTOM_HEADER_DIR ${PROJECT_NAME})
SET(CXX_DISABLE_WERROR TRUE) SET(CXX_DISABLE_WERROR TRUE)
# Doxygen setup
SET(DOXYGEN_USE_MATHJAX YES) SET(DOXYGEN_USE_MATHJAX YES)
SET(DOXYGEN_USE_TEMPLATE_CSS YES)
SET(DYNAMIC_GRAPH_PLUGINDIR "${CMAKE_INSTALL_PREFIX}/lib/${PROJECT_NAME}-plugins") SET(DYNAMIC_GRAPH_PLUGINDIR "${CMAKE_INSTALL_PREFIX}/lib/${PROJECT_NAME}-plugins")
SET(PACKAGE_EXTRA_MACROS "set(DYNAMIC_GRAPH_PLUGINDIR ${DYNAMIC_GRAPH_PLUGINDIR})") SET(PACKAGE_EXTRA_MACROS "set(DYNAMIC_GRAPH_PLUGINDIR ${DYNAMIC_GRAPH_PLUGINDIR})")
SET(PKG_CONFIG_EXTRA "plugindir=${DYNAMIC_GRAPH_PLUGINDIR}") SET(PKG_CONFIG_EXTRA "plugindir=${DYNAMIC_GRAPH_PLUGINDIR}")
......
This diff is collapsed.
...@@ -8,6 +8,8 @@ In dynamic-graph a graph is build with: ...@@ -8,6 +8,8 @@ In dynamic-graph a graph is build with:
- computational nodes which are entities \subpage subpage_entities. - computational nodes which are entities \subpage subpage_entities.
- directed edges which are created by connecting input and output signals - directed edges which are created by connecting input and output signals
\subpage subp_signals. \subpage subp_signals.
- commands which are expanding the capabilities of the entity
\subpage subpage_command
- managing the nodes is done through a factory \subpage subp_factory providing - managing the nodes is done through a factory \subpage subp_factory providing
classes and a way to create instances from this list of classes. classes and a way to create instances from this list of classes.
- the instances of node are handled through a pool \subpage subp_pool - the instances of node are handled through a pool \subpage subp_pool
......
...@@ -17,7 +17,7 @@ The sources are available through github at the following URL: ...@@ -17,7 +17,7 @@ The sources are available through github at the following URL:
href="https://github.com/stack-of-tasks/dynamic-graph">https://github.com/stack-of-tasks/dynamic-graph</a> href="https://github.com/stack-of-tasks/dynamic-graph">https://github.com/stack-of-tasks/dynamic-graph</a>
To clone: To clone:
\code \code{.sh}
git clone https://github.com/stack-of-tasks/dynamic-graph.git git clone https://github.com/stack-of-tasks/dynamic-graph.git
\endcode \endcode
......
/* Customizing Doxygen output */
/* Needed to allow line breaks in tables*/
.memberdecls {
table-layout: fixed;
width: 100%;
}
/* Needed to break long template names*/
.memTemplItemLeft {
white-space: normal !important;
word-wrap: break-word;
}
/* Needed to break long template names*/
.memItemLeft {
white-space: normal !important;
word-wrap: break-word;
}
<!-- HTML header for doxygen 1.8.11-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<link href="$relpath^sot.ico" rel="icon" type="image/x-icon">
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<!--BEGIN PROJECT_LOGO-->
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
<!--END PROJECT_LOGO-->
<!--BEGIN PROJECT_NAME-->
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">$projectname
<!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
</div>
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
</td>
<!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME-->
<!--BEGIN PROJECT_BRIEF-->
<td style="padding-left: 0.5em;">
<div id="projectbrief">$projectbrief</div>
</td>
<!--END PROJECT_BRIEF-->
<!--END !PROJECT_NAME-->
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN SEARCHENGINE-->
<td>$searchbox</td>
<!--END SEARCHENGINE-->
<!--END DISABLE_INDEX-->
</tr>
</tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->
...@@ -78,11 +78,11 @@ namespace command { ...@@ -78,11 +78,11 @@ namespace command {
template <class E, typename T> struct CommandVoid1 : public Command { template <class E, typename T> struct CommandVoid1 : public Command {
typedef boost::function<void(const T &)> function_t; typedef boost::function<void(const T &)> function_t;
typedef boost::function<void(E *, const T &)> memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T &);
CommandVoid1(E &entity, function_t function, const std::string &docString) CommandVoid1(E &entity, function_t function, const std::string &docString)
: Command(entity, boost::assign::list_of(ValueHelper<T>::TypeID), : Command(entity,
boost::assign::list_of
(ValueHelper<T>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -111,7 +111,6 @@ CommandVoid1<E, T> *makeCommandVoid1( ...@@ -111,7 +111,6 @@ CommandVoid1<E, T> *makeCommandVoid1(
E &entity, E &entity,
// The following syntaxt don't compile when not specializing the template // The following syntaxt don't compile when not specializing the template
// arg... why ??? // arg... why ???
// typename CommandVoid1<E,T>::memberFunction_t function ,
boost::function<void(E *, const T &)> function, boost::function<void(E *, const T &)> function,
const std::string &docString) { const std::string &docString) {
return new CommandVoid1<E, T>(entity, boost::bind(function, &entity, _1), return new CommandVoid1<E, T>(entity, boost::bind(function, &entity, _1),
...@@ -142,13 +141,12 @@ namespace command { ...@@ -142,13 +141,12 @@ namespace command {
template <class E, typename T1, typename T2> template <class E, typename T1, typename T2>
struct CommandVoid2 : public Command { struct CommandVoid2 : public Command {
typedef boost::function<void(const T1 &, const T2 &)> function_t; typedef boost::function<void(const T1 &, const T2 &)> function_t;
typedef boost::function<void(E *, const T1 &, const T2 &)> memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T1 &, const T2 &);
CommandVoid2(E &entity, function_t function, const std::string &docString) CommandVoid2(E &entity, function_t function, const std::string &docString)
: Command(entity, : Command(entity,
boost::assign::list_of(ValueHelper<T1>::TypeID)( boost::assign::list_of
ValueHelper<T2>::TypeID), (ValueHelper<T1>::TypeID)
(ValueHelper<T2>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -178,7 +176,6 @@ CommandVoid2<E, T1, T2> *makeCommandVoid2( ...@@ -178,7 +176,6 @@ CommandVoid2<E, T1, T2> *makeCommandVoid2(
E &entity, E &entity,
// The following syntaxt don't compile when not specializing the template // The following syntaxt don't compile when not specializing the template
// arg... why ??? // arg... why ???
// typename CommandVoid2<E,T1,T2>::memberFunction_t function ,
boost::function<void(E *, const T1 &, const T2 &)> function, boost::function<void(E *, const T1 &, const T2 &)> function,
const std::string &docString) { const std::string &docString) {
return new CommandVoid2<E, T1, T2>( return new CommandVoid2<E, T1, T2>(
...@@ -211,14 +208,13 @@ namespace command { ...@@ -211,14 +208,13 @@ namespace command {
template <class E, typename T1, typename T2, typename T3> template <class E, typename T1, typename T2, typename T3>
struct CommandVoid3 : public Command { struct CommandVoid3 : public Command {
typedef boost::function<void(const T1 &, const T2 &, const T3 &)> function_t; typedef boost::function<void(const T1 &, const T2 &, const T3 &)> function_t;
typedef boost::function<void(E *, const T1 &, const T2 &, const T3 &)>
memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T1 &, const T2 &, const T3);
CommandVoid3(E &entity, function_t function, const std::string &docString) CommandVoid3(E &entity, function_t function, const std::string &docString)
: Command(entity, : Command(entity,
boost::assign::list_of(ValueHelper<T1>::TypeID)( boost::assign::list_of
ValueHelper<T2>::TypeID)(ValueHelper<T3>::TypeID), (ValueHelper<T1>::TypeID)
(ValueHelper<T2>::TypeID)
(ValueHelper<T3>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -249,7 +245,6 @@ CommandVoid3<E, T1, T2, T3> *makeCommandVoid3( ...@@ -249,7 +245,6 @@ CommandVoid3<E, T1, T2, T3> *makeCommandVoid3(
E &entity, E &entity,
// The following syntaxt don't compile when not specializing the template // The following syntaxt don't compile when not specializing the template
// arg... why ??? // arg... why ???
// typename CommandVoid3<E,T1,T2>::memberFunction_t function ,
boost::function<void(E *, const T1 &, const T2 &, const T3 &)> function, boost::function<void(E *, const T1 &, const T2 &, const T3 &)> function,
const std::string &docString) { const std::string &docString) {
return new CommandVoid3<E, T1, T2, T3>( return new CommandVoid3<E, T1, T2, T3>(
...@@ -286,17 +281,16 @@ template <class E, typename T1, typename T2, typename T3, typename T4> ...@@ -286,17 +281,16 @@ template <class E, typename T1, typename T2, typename T3, typename T4>
struct CommandVoid4 : public Command { struct CommandVoid4 : public Command {
typedef boost::function<void(const T1 &, const T2 &, const T3 &, const T4 &)> typedef boost::function<void(const T1 &, const T2 &, const T3 &, const T4 &)>
function_t; function_t;
typedef boost::function<void(E *, const T1 &, const T2 &, const T3 &,
const T4 &)>
memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T1 &, const T2 &, const T3 &, typedef void (E::*memberFunction_ptr_t)(const T1 &, const T2 &, const T3 &,
const T4 &); const T4 &);
CommandVoid4(E &entity, function_t function, const std::string &docString) CommandVoid4(E &entity, function_t function, const std::string &docString)
: Command(entity, : Command(entity,
boost::assign::list_of(ValueHelper<T1>::TypeID)( boost::assign::list_of
ValueHelper<T2>::TypeID)(ValueHelper<T3>::TypeID)( (ValueHelper<T1>::TypeID)
ValueHelper<T4>::TypeID), (ValueHelper<T2>::TypeID)
(ValueHelper<T3>::TypeID)
(ValueHelper<T4>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -364,9 +358,6 @@ namespace dynamicgraph { ...@@ -364,9 +358,6 @@ namespace dynamicgraph {
namespace command { namespace command {
template <class E> struct CommandVerbose : public Command { template <class E> struct CommandVerbose : public Command {
typedef boost::function<void(std::ostream &)> function_t; typedef boost::function<void(std::ostream &)> function_t;
typedef boost::function<void(E *, std::ostream &)> memberFunction_t;
typedef void (E::*memberFunctionConst_ptr_t)(std::ostream &) const;
typedef void (E::*memberFunction_ptr_t)(std::ostream &);
CommandVerbose(E &entity, function_t function, const std::string &docString) CommandVerbose(E &entity, function_t function, const std::string &docString)
: Command(entity, EMPTY_ARG, docString), fptr(function) {} : Command(entity, EMPTY_ARG, docString), fptr(function) {}
...@@ -477,12 +468,12 @@ namespace command { ...@@ -477,12 +468,12 @@ namespace command {
template <class E, typename ReturnType, typename T> template <class E, typename ReturnType, typename T>
struct CommandReturnType1 : public Command { struct CommandReturnType1 : public Command {
typedef boost::function<ReturnType(const T &)> function_t; typedef boost::function<ReturnType(const T &)> function_t;
typedef boost::function<ReturnType(E *, const T &)> memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T &);
CommandReturnType1(E &entity, function_t function, CommandReturnType1(E &entity, function_t function,
const std::string &docString) const std::string &docString)
: Command(entity, boost::assign::list_of(ValueHelper<T>::TypeID), : Command(entity,
boost::assign::list_of
(ValueHelper<T>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -511,7 +502,6 @@ CommandReturnType1<E, ReturnType, T> *makeCommandReturnType1( ...@@ -511,7 +502,6 @@ CommandReturnType1<E, ReturnType, T> *makeCommandReturnType1(
E &entity, E &entity,
// The following syntaxt don't compile when not specializing the template // The following syntaxt don't compile when not specializing the template
// arg... why ??? // arg... why ???
// typename CommandReturnType1<E,T>::memberFunction_t function ,
boost::function<ReturnType(E *, const T &)> function, boost::function<ReturnType(E *, const T &)> function,
const std::string &docString) { const std::string &docString) {
return new CommandReturnType1<E, ReturnType, T>( return new CommandReturnType1<E, ReturnType, T>(
...@@ -544,15 +534,13 @@ namespace command { ...@@ -544,15 +534,13 @@ namespace command {
template <class E, typename ReturnType, typename T1, typename T2> template <class E, typename ReturnType, typename T1, typename T2>
struct CommandReturnType2 : public Command { struct CommandReturnType2 : public Command {
typedef boost::function<ReturnType(const T1 &, const T2 &)> function_t; typedef boost::function<ReturnType(const T1 &, const T2 &)> function_t;
typedef boost::function<ReturnType(E *, const T1 &, const T2 &)>
memberFunction_t;
typedef void (E::*memberFunction_ptr_t)(const T1 &, const T2 &);
CommandReturnType2(E &entity, function_t function, CommandReturnType2(E &entity, function_t function,
const std::string &docString) const std::string &docString)
: Command(entity, : Command(entity,
boost::assign::list_of(ValueHelper<T1>::TypeID)( boost::assign::list_of
ValueHelper<T2>::TypeID), (ValueHelper<T1>::TypeID)
(ValueHelper<T2>::TypeID),
docString), docString),
fptr(function) {} fptr(function) {}
...@@ -582,7 +570,6 @@ CommandReturnType2<E, ReturnType, T1, T2> *makeCommandReturnType2( ...@@ -582,7 +570,6 @@ CommandReturnType2<E, ReturnType, T1, T2> *makeCommandReturnType2(
E &entity, E &entity,
// The following syntaxt don't compile when not specializing the template // The following syntaxt don't compile when not specializing the template
// arg... why ??? // arg... why ???
// typename CommandReturnType2<E,T1,T2>::memberFunction_t function ,
boost::function<ReturnType(E *, const T1 &, const T2 &)> function, boost::function<ReturnType(E *, const T1 &, const T2 &)> function,
const std::string &docString) { const std::string &docString) {
return new CommandReturnType2<E, ReturnType, T1, T2>( return new CommandReturnType2<E, ReturnType, T1, T2>(
...@@ -611,4 +598,5 @@ inline std::string docCommandReturnType2(const std::string &doc, ...@@ -611,4 +598,5 @@ inline std::string docCommandReturnType2(const std::string &doc,
} // namespace command } // namespace command
} // namespace dynamicgraph } // namespace dynamicgraph
#endif // __dg_command_bind_h__ #endif // __dg_command_bind_h__
...@@ -14,6 +14,7 @@ ...@@ -14,6 +14,7 @@
namespace dynamicgraph { namespace dynamicgraph {
class Entity; class Entity;
namespace command { namespace command {
/// \ingroup dgraph
/// Abstract class for entity commands /// Abstract class for entity commands
/// ///
/// This class provide a mean to control entities from external /// This class provide a mean to control entities from external
......
...@@ -63,14 +63,50 @@ public: ...@@ -63,14 +63,50 @@ public:
static std::string ret("Entity"); static std::string ret("Entity");
return ret; return ret;
} }
/** \brief Returns the Entity documentation
\return The documentation is provided as std::string object.
*/
virtual std::string getDocString() const; virtual std::string getDocString() const;
/** \brief Test if a signal of name signame is present.
\return True if the signal is present, False otherwise
*/
bool hasSignal(const std::string &signame) const; bool hasSignal(const std::string &signame) const;
/** \brief Provides a reference to the signal named signalName.
\param signalName: Name of the signal
\return A reference to the signal with a temporal dependency.
*/
SignalBase<int> &getSignal(const std::string &signalName); SignalBase<int> &getSignal(const std::string &signalName);
/** \brief Provides a const reference to the signal named signalName.
\param signalName: Name of the signal
\return A const reference to the signal with a temporal dependency.
*/
const SignalBase<int> &getSignal(const std::string &signalName) const; const SignalBase<int> &getSignal(const std::string &signalName) const;
/** \brief Display the list of signals of this entity in output stream os.
\param os: the output stream where to display the list of signals.
\returns The output stream given in parameter.
*/
std::ostream &displaySignalList(std::ostream &os) const; std::ostream &displaySignalList(std::ostream &os) const;
/** \brief This method is used to write down in os the edges of the graph
by calling the signals writeGraph method.
\param os: The output stream where to write the informations.
\return os: The output stream.
*/
virtual std::ostream &writeGraph(std::ostream &os) const; virtual std::ostream &writeGraph(std::ostream &os) const;
/** \brief This method is used write in the output stream os the
signals names and the commands of the entity.
\param os: The output stream where to write the list of objects
related to the entity.
*/
virtual std::ostream &writeCompletionList(std::ostream &os) const; virtual std::ostream &writeCompletionList(std::ostream &os) const;
/** \brief Display information on the entity inside the output stream os.
*/
virtual void display(std::ostream &os) const; virtual void display(std::ostream &os) const;
virtual SignalBase<int> *test() { return 0; } virtual SignalBase<int> *test() { return 0; }
...@@ -78,9 +114,20 @@ public: ...@@ -78,9 +114,20 @@ public:
virtual void test2(SignalBase<int> *) { return; } virtual void test2(SignalBase<int> *) { return; }
const std::string &getCommandList() const; const std::string &getCommandList() const;
/** \brief Provides the std::map where all the commands are registered
\returns A map of pointers towards Command objects
*/
CommandMap_t getNewStyleCommandMap(); CommandMap_t getNewStyleCommandMap();
/** \brief Provides the pointer towards the Command object cmdName.
\param cmdName: Name of the command
*/
command::Command *getNewStyleCommand(const std::string &cmdName); command::Command *getNewStyleCommand(const std::string &cmdName);
/** \brief Provides a map of all the signals.
\returns A copy of the map with all the pointers towards
the entity signals.
*/
SignalMap getSignalMap() const; SignalMap getSignalMap() const;
/// \name Logger related methods /// \name Logger related methods
......
...@@ -38,6 +38,10 @@ private: ...@@ -38,6 +38,10 @@ private:
const Value *value_; const Value *value_;
}; };
/** \ingroup dgraph
\brief This class implements a variant design pattern to handle basic types in Command.
*/
class DYNAMIC_GRAPH_DLLAPI Value { class DYNAMIC_GRAPH_DLLAPI Value {
public: public:
enum Type { enum Type {
......
Supports Markdown
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