FSM: Enhanced documentation

diff --git a/src/Doxyfile b/src/Doxyfile
index 893aea939030b22aa64a56dfa9e11fe5901f9a3f..ad88850e53f255c45d8e4663a96e071ec6a264a1 100644 (file)
--- a/src/Doxyfile
+++ b/src/Doxyfile
@@ -532,7 +532,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = pathplan/test/
+EXAMPLE_PATH           = pathplan/test/ fsm/example
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

diff --git a/src/fsm/eventgen.py b/src/fsm/eventgen.py
index 73bfaf30e3ffdc721ce96d97ac6ea7f014045aad..a4f5d825552fd1f1bc60ca23b92096e7f84cf2a1 100755 (executable)
--- a/src/fsm/eventgen.py
+++ b/src/fsm/eventgen.py
@@ -1,4 +1,6 @@
 #!/usr/bin/env python
+## @file eventgen.py
+# Script to compile definition of additional FSM events to .c and .h sources.
 import sys
 import os
 import os.path

diff --git a/src/fsm/example/example_ev.py b/src/fsm/example/example_ev.py
new file mode 100644 (file)
index 0000000..a2eba46
--- /dev/null
+++ b/src/fsm/example/example_ev.py
@@ -0,0 +1,9 @@
+events = {
+    "tested" : {
+        "EV_PING" : "Description of the PING event",
+        "EV_OTHER" : "Other event"
+    },
+    "tester" : {
+        "EV_PONG" : "Description of the PONG event"
+    },
+}

diff --git a/src/fsm/fsm.h b/src/fsm/fsm.h
index c19ac497fe54cd21c2bc18f08143ec8e37ddca23..2830739f97863f40192f5e2377e9ba837bea0ed3 100644 (file)
--- a/src/fsm/fsm.h
+++ b/src/fsm/fsm.h
@@ -23,6 +23,7 @@ Content:
 - \ref fsm_general
 - \ref state_functions
 - \ref fsm_events
+- \ref fsm_usage
 - \ref subfsm
 
 \section fsm_general Introduction
@@ -33,7 +34,7 @@ can be generated internally (see ::fsm_common_events), by another FSM
 or by some other piece of code. Every FSM is defined by structure
 ::robo_fsm and a set of state functions. There is exactly one
 "current" state function at a given time. The goal of the current state
-functions is to react to the events. The reaction to the event can be
+functions is to react to events. The reaction to an event can be
 represented by an arbitrary piece of code that does something
 useful. It is also possible to change the current state (function) of
 FSM (so called state transition). Having several state functions, it
@@ -56,7 +57,7 @@ statement. The switch condition is the #FSM_EVENT macro, whose value
 is the identifier of the event (see section \ref fsm_events) to be
 handled. In the handling code you can execute whatever you want. If
 there is some data associated with the event, it can be retrieved by
-FSM_EVENT_PTR() or FSM_EVENT_INT(). Additionally, FSM infrastructure
+#FSM_EVENT_PTR or #FSM_EVENT_INT. Additionally, FSM infrastructure
 provides some useful functions and macros. To work with time, you can
 use FSM_TIMER(). To execute transition to another state, use
 FSM_TRANSITION() or SUBFSM_TRANSITION() (see \ref subfsm). To send an
@@ -79,8 +80,9 @@ FSM_STATE(my_state) {
 \endcode
 
 For the above to work, it is important to declare the macro @c FSM_<id>
-before including header with event definition and fsm.h. See \ref
-fsm_events.
+before including header with event definition and fsm.h. See the note in \ref
+fsm_events section. This means, that state functions for different
+FSMs have to be declared in separate files.
 
 \section fsm_events Events
 
@@ -104,14 +106,18 @@ working with events.
 
 These requirements are hard to achieve in plain C. Therefore,
 additional events for FSMs are declared as a data structure in Python
-and there is a Python script, which converts this definition to .h a
+and there is a Python script eventgen.py, which converts this definition to .h a
 .c files.
 
-The event definition (for example see roboevent.py) is a Python
-dictionary (associative array) called @c events. Keys to this dictionary
-are the lowercase identifiers of FSM. The value is another dictionary,
-which defines the events for that FSM. The key is the event identifier and
-value is a comment.
+The event definition is a Python dictionary (associative array) called
+@c events. Keys to this dictionary are the lowercase identifiers of
+FSM. The value is another dictionary, which defines the events for
+that FSM. The key is the event identifier and value is a comment. In
+the example below, event for two FSMs called "tested" and "tester" are
+defined. The "tested" FSM can handle additional events EV_PING and EV_OTHER and
+"tester" FSM handles "EV_PONG".
+
+\include example_ev.py
 
 The script, which generates .c and .h source code is called
 eventgen.py. In .h, there is one enum for each FSM with all events
@@ -125,10 +131,45 @@ fulfilled because recent versions of GCC warns if some enum member is
 not handled in switch statement (unless you use @c default statement).
 
 @note You have to always include the generated header file with events before fsm.h.
+If you do not do so, an error is generated.
 
 @note In the source, where you define your state function, you have to
 define macro @c FSM_&lt;id&gt;, where @c &lt;id&gt; is uppercase identifier of FSM
-as defined in event definition.
+as defined in event definition. If you do not do so, you get a compilation error
+on definition of state function. GCC generates this error message:
+@verbatim
+error: expected ‘=’, ‘,’, ‘;’, ‘asm’ or ‘__attribute__’ before ‘FSM_XXX_not_defined’
+@endverbatim
+
+\section fsm_usage Usage
+
+To use FSMs provided by this library in your application, you need to
+-# define additional event for your automatons (see section \ref fsm_events),
+-# define state functions for your automatons (see section \ref
+state_functions) and
+-# start execution of the automatons (every FSM executes in its own thread).
+
+Definition of state functions usually starts with lines like this:
+@code
+#define FSM_SOME_NAME // define which FSM state functions are to be declared here
+#include "events.h"   // include definition of additional events (generated from events.py)
+#include <fsm.h>
+
+FSM_STATE(test_state1) {
+        ...
+}
+@endcode
+
+Starting the execution of the automaton usually looks like:
+@code
+struct robo_fsm fsm;
+fsm_init(&fsm, "id_for_debug_massages");
+fsm.state = &fsm_state_test_state1;       // Initial state of the automaton
+if (fsm_start(&fsm, NULL) != 0) {
+       perror("fsm_start");
+       exit(1);
+}
+@endcode
 
 \section subfsm Sub-Automatons
 

diff --git a/src/fsm/fsm_common_events.h b/src/fsm/fsm_common_events.h
index 8b76f756e3f026a4e6328f6f17babc5e9bbfbcc9..8022465bfe0d9cc7f81319d793a3bdd8127b2f7f 100644 (file)
--- a/src/fsm/fsm_common_events.h
+++ b/src/fsm/fsm_common_events.h
@@ -23,7 +23,7 @@ enum fsm_common_events {
         * A transition to ANOTHER state is happening. If a
         * transition is to the same state or to a sub-atomaton, this
         * event doesn't occur. This is the last event sent before the
-        * state is changed, but fsm->state already points to the next
+        * state is changed, but robo_fsm::state already points to the next
         * state.
         *
         * @warning The behavior is undefined if state is changed