Add further documentation

extractor/extraction_containers.cpp

@@ -301,6 +301,7 @@ void ExtractionContainers::PrepareData(const std::string &output_file_name,
         node_iterator = all_nodes_list.begin();
         edge_iterator = all_edges_list.begin();
 
+        // Also serializes the edges
         while (edge_iterator != all_edges_list.end() && node_iterator != all_nodes_list.end())
         {
             if (edge_iterator->target < node_iterator->node_id)
@@ -329,6 +330,8 @@ void ExtractionContainers::PrepareData(const std::string &output_file_name,
                 int integer_weight = std::max(
                     1, (int)std::floor(
                            (edge_iterator->is_duration_set ? edge_iterator->speed : weight) + .5));
+                // FIXME: This means we have a _minimum_ edge length of 1m
+                // maybe use dm as base unit?
                 const int integer_distance = std::max(1, (int)distance);
                 const short zero = 0;
                 const short one = 1;

extractor/extractor.cpp

@@ -64,6 +64,24 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include <unordered_map>
 #include <vector>
 
+/**
+ * TODO: Refactor this function into smaller functions for better readability.
+ *
+ * This function is the entry point for the whole extraction process. The goal of the extraction
+ * step is to filter and convert the OSM geometry to something more fitting for routing.
+ * That includes:
+ *  - extracting turn restrictions
+ *  - splitting ways into (directional!) edge segments
+ *  - checking if nodes are barriers or traffic signal
+ *  - discarding all tag information: All relevant type information for nodes/ways
+ *    is extracted at this point.
+ *
+ * The result of this process are the following files:
+ *  .names : Names of all streets, stored as long consecutive string with prefix sum based index
+ *  .osrm  : Nodes and edges in a intermediate format that easy to digest for osrm-prepare
+ *  .restrictions : Turn restrictions that are used my osrm-prepare to construct the edge-expanded graph
+ *
+ */
 int extractor::run(const ExtractorConfig &extractor_config)
 {
     try
@@ -83,6 +101,7 @@ int extractor::run(const ExtractorConfig &extractor_config)
         // setup scripting environment
         ScriptingEnvironment scripting_environment(extractor_config.profile_path.string().c_str());
 
+        // used to deduplicate street names: actually maps to name ids
         std::unordered_map<std::string, NodeID> string_map;
         string_map[""] = 0;