From 8282bdb08791f2631a9d51e75b988077d903f3d1 Mon Sep 17 00:00:00 2001
From: Michael Andreen <harv@ruin.nu>
Date: Fri, 3 Jun 2005 10:01:19 +0000
Subject: [PATCH] more documentation

---
 node.h    | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 planner.h | 29 +++++++++++++++++++++++++
 2 files changed, 94 insertions(+)

diff --git a/node.h b/node.h
index cbe1734..4b8708d 100644
--- a/node.h
+++ b/node.h
@@ -5,37 +5,102 @@
 #include <utility>
 #include "action.h"
 
+/**
+ * A node in the plan graph, corresponds to a single action.
+ */
 class Node {
 
 	public:
+		/**
+		 * Creates a node for the given action.
+		 */
 		Node(const Action* action);
+
+		/**
+		 * Creates an empty, non-functional, node.
+		 */
 		Node();
+
+		/**
+		 * Creates a copy of the given node.
+		 */
 		Node(const Node& node);
 		virtual ~Node(){}
+
+		/**
+		 * Add a child node, which will be executed after this node.
+		 */
 		void addChild(Node* node);
+
+		/**
+		 * Returns the action this node corresponds to.
+		 */
 		const Action* action() const;
+
+		/**
+		 * Execute this node, and hence the corresponding action.
+		 * Sets the effects achieved.
+		 *
+		 * If _executed is true or _preconditions.size() > 0 this method will
+		 * just return.
+		 */
 		void execute();
+
+		/**
+		 * Checks if this node has been executed or not.
+		 */
 		bool executed() const;
+
+		/**
+		 * Returns the effects that was achieved from execution.
+		 */
 		const Literals& effects() const;
+
+		/**
+		 * Satisfy a single condition.
+		 */
 		bool satisfyCondition(std::string effect);
+
+		/**
+		 * Satisfies a list of conditions.
+		 */
 		bool satisfyConditions(const Literals& effects);
+
+		/**
+		 * Returns all the children to this node.
+		 */
 		const std::vector<Node*>& children() const;
+
+		/**
+		 * Returns the unsatisfied preconditions.
+		 */
 		const Preconditions& preconditions() const;
 
 	protected:
+		//! The action this node corresponds to.
 		const Action* _action;
+		//! The list of children to this node.
 		std::vector<Node*> _children;
+		//! The, so far, unsatisfied preconditions.
 		Preconditions _preconditions;
+		//! Will be true if this node has been executed.
 		bool _executed;
+		//! The effects which were achieved by the execution.
 		Literals _effects;
 };
 
+/**
+ * Class which is used as the start node in the plan graph.
+ */
 class StartNode :public Node {
 	public:
 		StartNode(const Literals& init);
 		~StartNode(){delete _action;}
 };
 
+/**
+ * Class which is used as the end node in the plan graph.
+ */
 class EndNode :public Node {
 	public:
 		EndNode(const Literals& goal);
diff --git a/planner.h b/planner.h
index fc49df9..c6f23b2 100644
--- a/planner.h
+++ b/planner.h
@@ -10,6 +10,9 @@
 
 class Node;
 
+/**
+ * This class creates, holds and executes a plan.
+ */
 class Planner {
 	public:
 		/**
@@ -59,21 +62,47 @@ class Planner {
 		 * executeChildren for these nodes.
 		 */
 		void executePlan();
+
+		/**
+		 * Iterates through the children of the input node and satisfies all
+		 * preconditions possible with this node. The children will be executed
+		 * if all preconditions have been satisfied.
+		 */
 		int executeChildren(Node* node);
+
+		/**
+		 * Addes the remaining actions to the actions map, creates new start and
+		 * finish nodes and runs makePlan.
+		 */
 		void replan();
+		
+		/**
+		 * Deletes all nodes, updates _init and _goal, and clears the internal maps and vector.
+		 */
 		int cleanupExecution();
 
+		//! Semaphore which is used to signal if a new node has been executed and added to _executedNodes.
 		sem_t _nodes;
+		//! Mutex for access to _executedNodes.
 		sem_t _list;
+		//! Holds the nodes which have been executed, but the children haven't been taken care of yet.
 		std::queue<Node*> _executedNodes;
 
+		//! The start node in the plan graph.
 		Node* _start;
+		//! The end node in the plan graph.
 		Node* _finish;
+		//! Map from all the effects which can be achieved with the already added nodes.
 		__gnu_cxx::hash_map<std::string,Node*> _addedEffects;
+		//! Map with all effects available and their corresponding actions.
 		__gnu_cxx::hash_map<std::string,Action*> _actionEffects;
+		//! The initial state.
 		Literals _init;
+		//! The goal state
 		Literals _goal;
+		//! All the nodes added to the current plan.
 		std::vector<Node*> _addedNodes;
+		//! All the non-executed actions available in the current plan.
 		std::vector<Action*> _actions;
 };
 #endif
-- 
2.39.2