UndirectedGraphSearchExample javadoc updated [skip-ci]

hipster-examples/src/main/java/es/usc/citius/hipster/examples/RomanianProblemExample.java

@@ -43,6 +43,7 @@ public static void main(String[] args) throws InterruptedException {
             a HipsterGraph.
          */
         SearchProblem problem = GraphSearchProblem
+
                 /*
                     Here we set the start of the search problem to the city Arad.
                  */
@@ -73,7 +74,12 @@ public static void main(String[] args) throws InterruptedException {
 
 
         /**
-         * Search is executed with with goal set to Bucharest. Results of the search are printed.
+         * Search iterators can be easily created using the methods in the Hipster class. This allows
+         * you to instantiate several search algorithms using the information stored in SearchProblem created
+         * above.
+         *
+         * In this example the search is executed using A* with with the goal set to Bucharest.
+         * Search will stop when the algorithm explores that node. Results of the search are printed.
          */
         System.out.println(Hipster.createAStar(problem).search(RomanianProblem.City.Bucharest));
     }

hipster-examples/src/main/java/es/usc/citius/hipster/examples/UndirectedGraphSearchExample.java

@@ -8,26 +8,34 @@
 import es.usc.citius.hipster.model.problem.SearchProblem;
 
 /**
- * This example creates an undirected graph
- * {@link es.usc.citius.hipster.graph.HipsterGraph} and performs a simple search
- * using DFS.
- * 
- * We use the GraphSearchProblem util
- * {@link es.usc.citius.hipster.model.problem.SearchProblem} to create the
- * problem. The initial state (since we are dealing with graphs, this means
- * initial node) is set using this util, as well as other aspects of the search
- * problem such as the cost associated with each action (since we are dealing
- * with graphs the cost is simply the cost of the edge).
- * 
- * We finally set the goal state (aka the node to find) and print.
+ * Example of graph search with manual creation of the graph structure.
+ * <p>
+ * In this example an undirected {@link HipsterGraph} is created, and then
+ * a search using DFS is executed. Summarized characteristics of this
+ * example are:
+ * <ul>
+ *      <li>Uses {@link GraphSearchProblem}, a subclass of {@link SearchProblem} specially designed to facilitate
+ *      working with graph search problems.</li>
+ *      <li>An undirected graph is created introducing manually the data in the {@link HipsterGraph}.</li>
+ *      <li>Cost function takes the cost of moving between cities from the arcs of the graph.</li>
+ * </ul>
+ *
+ * In this example the search problem is defined from the initial state, extracting the costs from the arcs
+ * of the graph. The goal is set after creating the search problem, at the end.
+ * <p>
+ * Since DFS is an uninformed search algorithm an heuristic is not needed to be defined.
+ *
+ * @author Pablo Rodríguez Mier <<a href="mailto:pablo.rodriguez.mier@usc.es">pablo.rodriguez.mier@usc.es</a>>
+ * @author Adrián González Sieira <<a href="adrian.gonzalez@usc.es">adrian.gonzalez@usc.es</a>>
  */
-
 public class UndirectedGraphSearchExample {
 
 	public static void main(String args[]) {
 
-		// Here we create a simple, undirected graph using Hipster.
-		// Note this graph is essentially a tree.
+		/*
+		    Here a HipsterGraph is created. The builder allows to specify both nodes connected by each
+		    arc and its cost.
+         */
         HipsterGraph<String,Double> graph =
                 GraphBuilder.<String,Double>create() 
                 .connect("A").to("B").withEdge(2d)
@@ -40,24 +48,61 @@ public static void main(String args[]) {
                 .connect("C").to("I").withEdge(5d)
                 .connect("C").to("J").withEdge(10d)
                 .connect("C").to("K").withEdge(5d)
-                .connect("K").to("L").withEdge(5d)          
+                .connect("K").to("L").withEdge(5d)
+                /*
+                    Finally the graph is instantiated with the methods createDirectedGraph or
+                    createUndirectedGraph, like in this example.
+                 */
                 .createUndirectedGraph();
 
-		// Here we create the search problem using the GraphSearchProblem util.
-		// We use {@link GraphSearchProblem#takeCostsFromEdges}to give edges a
-		// cost - however
-		// {@link GraphSearchProblem#useGenericCosts} can also be used to give
-		// each edge a unitary cost
+        /*
+            SearchProblem is the structure used by Hipster to store all the
+            information about the search query, like: start, goals, transition function,
+            cost function, etc. Once created it is used to instantiate the search
+            iterators which provide the results.
 
+            GraphSearchProblem is a subclass of SearchProblem which provides implementations for TransitionFunction and
+            CostFunction which directly extract the information of connectivity between node and cost of the arcs from
+            a HipsterGraph.
+         */
 		SearchProblem p = GraphSearchProblem
+
+                /*
+                    Here we set the start of the search problem to the node "A".
+                 */
 				.startingFrom("A")
+
+                /*
+                    Defines the graph which is used as source to instantiate this GraphSearchProblem. Here
+                    is where all the information of nodes and arcs is stored. This sets a TransitionFunction
+                    which creates the Transitions between states from the information stored in this HipsterGraph.
+                 */
 				.in(graph)
+
+                /*
+                    The graph that we use in this example contains the weights of the arcs. These weights are
+                    the stored in the arcs. Function {@link GraphSearchProblem#takeCostsFromEdges}
+                    creates a CostFunction that extracts the costs of each Transition from the HipsterGraph.
+
+                    Alternatively you can use the method extractCostsFromEdges if you need to apply any operation over
+                    the costs labeled in the edges of the graph.
+                 */
 				.takeCostsFromEdges()
+
+                /*
+                    With this method the SearchProblem is instantiated using the data introduced with the methods
+                    above.
+                 */
 				.build();
 
-		// Search the shortest path from "A" to "L". The search will stop when
-		// the goal state
-		// is reached - aka when L is reached.
+        /**
+         * Search iterators can be easily created using the methods in the Hipster class. This allows
+         * you to instantiate several search algorithms using the information stored in SearchProblem created
+         * above.
+         *
+         * In this example the search is executed using DFS with with the goal set to "L". Search will stop
+         * when the algorithm explores that node. Results of the search are printed.
+         */
 		System.out.println(Hipster.createDepthFirstSearch(p).search("L"));
 	}
 }