Added some final comments to C++ code

src/emscripten.pathfinding.cpp

@@ -1,3 +1,8 @@
+// This file is used by jquery.wayfinding.js plugin to run Dijkstra's between to SVG rooms.
+// It is compiled to JavaScript using the Emscripten compiler
+// The binding of the C++ functions to JavaScript is done using Emscripten's Embind feature
+// RapidJSON is used to parse the stringified JSON passed when called by JavaScript code.
+
 #include <string>
 #include <set>
 #include <vector>
@@ -10,6 +15,8 @@
 using namespace rapidjson;
 using namespace std;
 
+// There are three types of nodes in our datastore.
+// The stop type is used to indicated the end of the path generated by Dijkstra's
 enum nodeType {path, door, portal, stop};
 string stringTypes[] = {"path", "door", "portal", "stop"};
 
@@ -35,18 +42,26 @@ class Node
     int pathID;
 
     // Door stuff
-    // The door's name
+    // The door's name. typically looks like "R123"
     string doorID;
+    // These bools are used to indicate if the node is the starting or ending node for Dijkstras
     bool start;
     bool end;
 
     // Portal stuff
     string portalID;
+    // Portals pair with other portals located on different floors
+    // toFloor indicates what floor at portal's pair is on
+    // matchID is the ID of the portal's pair
+    // both are -1 if a portal does not have a pair
     int toFloor;
     int matchID;
+    // Usually, there are two types of portals: stairs or elevators
+    // This is to indicate if a portal is wheelchair accessible (elevators) for the Dijkstras code
     bool accessible;
 
     // Orders nodes by ID, floor, and type, in that order.
+    // Need to use priority queue for pathfinding
     bool operator<(const Node other) const
     {
       if (id == other.id) {
@@ -71,6 +86,8 @@ class Graph
     // number of floors in the graph
     int floors;
 
+    // This is set to true in Dijkstra's if a path is found between the start and end
+    // This is used to indicated if a no path found error has occurred
     bool foundPath = false;
 
     vector< vector<Node> > paths;
@@ -79,6 +96,8 @@ class Graph
 
     // Finds the shortest path from (startFloor, startID) to (endFloor, endID)
     // Returns a map containing the route in reverse.
+    // Accessible indicates whether to find a wheelchair accesible path
+    // Called only by the pathfinding function
     map<Node, Node> dijkstra(int startID, int startFloor, int endID,
         int endFloor, bool accessible)
     {
@@ -88,6 +107,7 @@ class Graph
       map<Node, Node> path;
       map<Node, int> minDist;
 
+      // Set all node distances to infinity
       for (int floor = 0; floor < floors; floor++)
       {
         for (auto node : doors[floor])
@@ -106,10 +126,12 @@ class Graph
         }
       }
 
+      // Mark the start node
       minDist[start] = 0;
       path[start] = Node();
       path[start].type = stop;
 
+      // Set up our priority queue
       set< pair<int, Node> > activeNodes;
       activeNodes.insert({0, start});
 
@@ -118,6 +140,7 @@ class Graph
         // extract the next node to be processed
         Node currentNode = activeNodes.begin()->second;
         if (currentNode.type == door) {
+          // Stop if we've reached our destination
           if (currentNode.id == end.id && currentNode.floor == end.floor)
           {
             foundPath = true;
@@ -147,6 +170,7 @@ class Graph
         for (auto neighborID : currentNode.portals)
         {
           Node neighbor = portals[currentNode.floor][neighborID];
+          // If we're looking for an accessible route and the current portal is not, skip it
           if (accessible && !neighbor.accessible)
           {
             continue;
@@ -158,7 +182,7 @@ class Graph
             path[neighbor] = currentNode;
           }
         }
-        // Look at match
+        // Need to add the portal's pair to the set of nodes to be visited
         if (currentNode.type == portal && currentNode.matchID != -1 && currentNode.toFloor != -1)
         {
           Node neighbor = portals[currentNode.toFloor][currentNode.matchID];
@@ -170,6 +194,8 @@ class Graph
         }
       }
 
+      foundPath = false;
+      // If the destination was never reached, return this empty route
       map<Node, Node> error{{Node(), Node()}};
       return error;
     }
@@ -183,7 +209,11 @@ class Graph
     }
 };
 
-// change name
+// This function is called by JavaScript code by writing Module.pathfinding()
+// dataStore should be stringified JSON of the map datastore
+// startString & endString are the room names of the start and end point
+// accessible is to indicated whether the user wants a wheelchair accessible route
+// Returns a vector<string> that is JavaScript is able to work with
 vector<string> pathfinding(string dataStore, string startString,
     string endString, bool accessible)
 {
@@ -206,9 +236,10 @@ vector<string> pathfinding(string dataStore, string startString,
   graph.paths.resize(graph.floors);
   graph.portals.resize(graph.floors);
 
+  // Go through each floor in datastore and make the graph object
   for (int floor = 0; floor < graph.floors; floor++)
   {
-    // Get doors
+    // Turn doors into nodes
     Value& doorElements = document["doors"][floor];
 
     for (int index = 0; index < doorElements.Size(); index++)
@@ -220,6 +251,7 @@ vector<string> pathfinding(string dataStore, string startString,
       doorNode.doorID = doorElements[index]["doorId"].GetString();
       doorNode.weight = 0;
 
+      // Check for start and end nodes
       if (doorNode.doorID == startString)
       {
         doorNode.start = true;
@@ -259,7 +291,7 @@ vector<string> pathfinding(string dataStore, string startString,
       graph.doors[floor].push_back(doorNode);
     } // end of doors
 
-    // Get paths
+    // Turn paths into nodes
     Value& pathElements = document["paths"][floor];
 
     for (int index = 0; index < pathElements.Size(); index++)
@@ -290,7 +322,7 @@ vector<string> pathfinding(string dataStore, string startString,
       graph.paths[floor].push_back(pathNode);
     } // end of paths
 
-    // Get portals
+    // Turn portals into nodes
     Value& portalElements = document["portals"][floor];
 
     for (int index = 0; index < portalElements.Size(); index++)
@@ -328,8 +360,13 @@ vector<string> pathfinding(string dataStore, string startString,
   } // end of floors
 
   // Run dijkstra's
+  // elements will hold the returned path from Dijkstra's
+  // This will also hold an error if one occurs
+  // Possible errors are invalid rooms or no path between rooms
   vector<string> elements;
 
+  // Check if the start and/or end room were not found
+  // If so, return an error
   if (startID == -1 && startFloor == -1 && endID == -1 && endFloor == -1)
   {
     string error;
@@ -362,6 +399,9 @@ vector<string> pathfinding(string dataStore, string startString,
       int pathCount = 0;
       Node target = graph.doors[endFloor][endID];
 
+      // Add the nodes from the route to the element vector
+      // Strings are pushed into
+      // The strings have the format nodetype-nodefloor-nodeid. Ex: path-0-1
       while (route[target].type != stop)
       {
         el = stringTypes[target.type] + "-" + to_string(target.floor) + "-" +
@@ -371,12 +411,14 @@ vector<string> pathfinding(string dataStore, string startString,
         pathCount++;
       }
 
+      // Make sure to the get last node
       el = stringTypes[target.type] + "-" + to_string(target.floor) + "-" +
         to_string(target.id);
       elements.push_back(el);
     }
     else
     {
+      // No route was found, so return error
       string error;
       error = "Path not found between start: " + startString + " & end: ";
       error += endString;
@@ -387,6 +429,9 @@ vector<string> pathfinding(string dataStore, string startString,
   return elements;
 }
 
+// Emscripten bindings
+// JavaScript needs to know how to handle a vector<string>
+// pathfinding is the function we want JavaScript to call
 EMSCRIPTEN_BINDINGS(my_module) {
   emscripten::register_vector<string>("VectorString");
   emscripten::function("pathfinding", &pathfinding);