Docs added

Author: facontidavide

docs/BT_basics.md

@@ -10,71 +10,76 @@ our coordinating component interacts with the rest of the system.
 For instance, in a service-oriented architecture, the leaves would contain
 the "client" code that triggers an action.
 
-All the other nodes of the tree, those which are not leaves, control the 
+The other nodes of the tree, those which are not leaves, control the 
 "flow of execution".
 
 To better understand how this flow takes place , imagine a signal, that we will further
 call "__tick__" that is executed at the __root__ of the tree and propagates through
-the branches until it reaches a leave.
+the branches until it reaches one or multiple leaves.
 
 The result of a tick can be either:
 
 - __SUCCESS__
 - __FAILURE__
 - __RUNNING__
 
+
 The first two, as their names suggest, inform their parent that their operation
  was a success or a failure.
-The latter usually means that the execution of the TreeNode is not completed
-and it needs more time to return a valid result.
+
+RUNNING is returned by asynchronous nodes when their execution is not completed
+and they needs more time to return a valid result.
+
+This C++ library provides also the status __IDLE__; it means that the node is ready to
+start.
 
 The result of a node is propagated back to the parent, that will decide
-which child should be ticked next or will return a result itself.
+which child should be ticked next or will return a result to its own parent.
 
 ## Types of nodes
 
 __ControlNodes__ are nodes which can have 1 to N children. Once a tick
 is received, this tick may be propagated to one or more of the children.
 
-__DecoratorNodes__ can have only a single child. 
+__DecoratorNodes__ is similar to the ControlNode, but it can have only a single child. 
 
 __ActionNodes__ are leaves and do not have children. The user should implement
-their own ActionNodes that perform the actual task.
+their own ActionNodes to perform the actual task.
 
-__ConditionNodes__ are equivalent to ActionNodes, with the exeption that
-they are alwais aotmic (they should not return RUNNING) and they should not 
+__ConditionNodes__ are equivalent to ActionNodes, but
+they are always atomic, i.e. they must not return RUNNING. They should not 
 alter the state of the system.
 
 ![UML hierarchy](images/TypeHierarchy.png)
 
-!!! note
-    Actions and Conditions differ only in terms of __semantic__. 
-    From an implementation point of view they are the same.
 
 ## Learn by example
 
-To better understand how a BehaviorTrees work let's focus on some practical
+To better understand how a BehaviorTrees work, let's focus on some practical
 examples. For the sake of simplicity we will not take into account what happens
 when an action returns RUNNING.
 
 We will assume that each Action is executed atomically and synchronously.
-In future sections we will more thoughtfully analyze asynchronous actions.
+
 
 ### Sequence
 
 Let's illustrate how a BT works using the most basic and frequently used 
 ControlNode: the [SequenceNode](SequenceNode.md).
 
+The children of a ControlNode are always __ordered__; it is up to the ControlNode
+to consider this order or not.
+
+In the graphical representation, the order of execution is __from left to right__.
+
 ![Simple Sequence: fridge](images/SequenceBasic.png)
 
-It is important to notice that the children of a ControlNode are __ordered__.
-In this case the order of execution is __from left to right__.
 
-A Sequence works as described next:
+In short:
 
 - If a child returns SUCCESS, tick the next one.
 - If a child returns FAILURE, then no more children are ticked and the Sequence returns FAILURE.
-- If all the children return SUCCESS, then the Fallback returns SUCCESS too.
+- If all the children return SUCCESS, then the Sequence returns SUCCESS too.
 
 ??? warning "Exercise: find the bug! Expand to read the answer."
     If the action __GrabBeer__ fails, the door of the 
@@ -87,7 +92,7 @@ The goal of a [DecoratorNode](DecoratorNode.md) is either to transform the resul
 from the child, to terminate the child, 
 or repeat ticking of the child, depending on the type of Decorator.
 
-You can create your own Decorators too.
+You can create your own Decorators.
 
 ![Simple Decorator: Enter Room](images/DecoratorEnterRoom.png)
 
@@ -116,18 +121,17 @@ __But__ there is an error. Can you find it?
 
 ### Fallback
 
-[FallbackNodes](FallbackNode.md), known also as __"Selector"__ in the literature,
-Is a node that is used to express, as the name suggests, fallback strategies, 
-ie. what to do if a child return FAILURE.
+[FallbackNodes](FallbackNode.md), known also as __"Selector"__,
+are nodes that can express, as the name suggests, fallback strategies, 
+ie. what to do next if a child returns FAILURE.
 
-In short, it ticks the children in order, as usual from left to right and:
+In short, it ticks the children in order and:
 
 - If a child returns FAILURE, tick the next one.
 - If a child returns SUCCESS, then no more children are ticked and the Fallback returns SUCCESS.
 - If all the children return FAILURE, then the Fallback returns FAILURE too.
 
 In the next example, you can see how Sequence and Fallbacks can be combined:
-
 
 ![FallbackNodes](images/FallbackBasic.png)  
 
@@ -162,11 +166,11 @@ returns FAILURE.
 Both the trees will close the door of the fridge, eventually, but:
 
 - the tree on the __left__ side will always return SUCCESS if we managed to
- open and clode the fridge.
+ open and close the fridge.
 - the tree on the __right__ side will return SUCCESS if the beer was there, 
 FAILURE otherwise.
 
-We can easily double-check that everything works as usual if __GrabBeer__ returns SUCCESS.
+Everything works as expected if __GrabBeer__ returns SUCCESS.
 
 ![FetchBeer success](images/FetchBeer2.png)
 

docs/ControlNode.md

@@ -5,7 +5,7 @@ A decorator is a node that can have only a single child.
 It is up to the Decorator to decide if, when and how many times the child should be
 ticked.
 
-## InverterNode
+## NegationNode
 
 Tick the child once and return SUCCESS if the child failed or FAILURE if
 the child succeeded.
@@ -26,7 +26,7 @@ Otherwise, it returns always FAILURE.
 
 ## RepeatNode
 
-Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
+Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameters.md),
 as long as the child returns SUCCESS.
 
 Interrupt the loop if the child returns FAILURE and, in that case, return FAILURE too.
@@ -35,19 +35,11 @@ If the child returns RUNNING, this node returns RUNNING too.
 
 ## RetryNode
 
-Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
+Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameters.md),
 as long as the child returns FAILURE.
 
 Interrupt the loop if the child returns SUCCESS and, in that case, return SUCCESS too.
 
 If the child returns RUNNING, this node returns RUNNING too.
 
-## RetryNode
-
-Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
-as long as the child returns FAILURE.
-
-Interrupt the loop if the child returns SUCCESS and, in that case, return SUCCESS too.
-
-If the child returns RUNNING, this node returns RUNNING too.
 

docs/DecoratorNode.md

@@ -4,63 +4,103 @@ This family of nodes are known as "Selector" or, sometimes, "Priority"
 in other frameworks.
 
 Its purpose is to try different strategies, until we find one that "works".
-Currently, there is only a single type of node called "FallbackNode".
 
+Currently the framework provides two kinds of nodes:
 
-## FallbackNode
+- FallbackNode
+- FallbackStarNode
+
+They share the following rules:
 
-The SequenceNode is used to execute the children in a sequence.
+- Before ticking the first child, the node status becomes __RUNNING__.
 
-- Before ticking the first child, Fallback becomes __RUNNING__.
 - If a child returns __FAILURE__, it ticks the next child.
+
 - If the __last__ child returns __FAILURE__ too, all the children are halted and
- the Sequence returns __FAILURE__.
-- If a child returns __RUNNING__, Fallback suspends and returns __RUNNING__.
-- If a child returns __SUCCESS__, Fallback stops and returns __SUCCESS__. 
+ the sequence returns __FAILURE__.
+ 
+- If a child returns __SUCCESS__, it stops and returns __SUCCESS__.
+  All the children are halted. 
+
+
+## FallbackNode
+
+If a child returns __RUNNING__:
+
+- FallbackNode returns __RUNNING__. 
+- The loop is restarted and  all the previous children are ticked again __unless
+  they are ActionNodes__. 
+
 
 __Example__:
 
-Try different strategies to open the door. Check first if it is open already.
+Try different strategies to open the door. Check first if the door is open.
 
 ![FallbackNode](images/FallbackSimplified.png)
 
 ??? example "See the pseudocode"
 	``` c++
-		// At the beginning, start from first child 
-		if( state != RUNNING) {
-			index = 0;
+		status = RUNNING;
+
+		for (int index=0; index < number_of_children; index++)
+		{
+			child_status = child[index]->tick();
+			
+			if( child_status == RUNNING ) {
+				// Suspend execution and return RUNNING.
+				// At the next tick, index will be the same.
+				return RUNNING;
+			}
+			else if( child_status == SUCCESS ) {
+				// Suspend execution and return SUCCESS.
+				// index is reset and children are halted.
+				HaltAllChildren();
+				return SUCCESS;
+			}
 		}
-		state = RUNNING;
+		// all the children returned FAILURE. Return FAILURE too.
+		HaltAllChildren();
+		return FAILURE;
+	```	
+
+## FallbackStarNode
+
+If a child returns __RUNNING__:
+
+- FallbackStarNode returns __RUNNING__. 
+- The loop is __not__ restarted and  none of the previous children is ticked.
+
+??? example "See the pseudocode"
+	``` c++
+		// index is initialized to 0 in the constructor
+		status = RUNNING;
 
 		while( index < number_of_children )
 		{
-			child_state = child[index]->tick();
+			child_status = child[index]->tick();
 			
-			if( child_state == RUNNING ) {
+			if( child_status == RUNNING ) {
 				// Suspend execution and return RUNNING.
 				// At the next tick, index will be the same.
-				state = RUNNING;
-				return state;
+				return RUNNING;
 			}
-			else if( child_state == FAILURE ) {
+			else if( child_status == FAILURE ) {
 				// continue the while loop
 				index++;
 			}
-			else if( child_state == SUCCESS ) {
+			else if( child_status == SUCCESS ) {
 				// Suspend execution and return SUCCESS.
-				// index is reset and children are halted.
-				state = SUCCESS;
+				// At the next tick, index will be the same.
+   			    HaltAllChildren();
 				index = 0;
-				HaltAllChildren();
-				return state;
+				return SUCCESS;
 			}
 		}
-		// all the children returned failure. Return FAILURE too.
-		state = FAILURE;
+		// all the children returned FAILURE. Return FAILURE too.
+		index = 0;
 		HaltAllChildren();
-		return state;
-
-
+		return FAILURE;
+	```	
 
 
 

docs/FallbackNode.md

@@ -0,0 +1,3 @@
+# NodeParameters
+
+