Comments and docs

NOTES.md

@@ -1,3 +1,17 @@
+## Code Layout
+
+This follows a similar layout to d3: each module of d3 has a file with its exact
+name, like
+
+```javascript
+// format.js
+
+iD.format = {};
+```
+
+And the parts of that module are in separate files that implement `iD.format.XML`
+and so on.
+
 ## The Graph
 
 iD implements a [persistent data structure](http://en.wikipedia.org/wiki/Persistent_data_structure)

index.html

@@ -47,8 +47,10 @@
         <script type='text/javascript' src='js/iD/actions/actions.js'></script>
         <script type='text/javascript' src='js/iD/actions/operations.js'></script>
 
+        <script type='text/javascript' src='js/iD/format/format.js'></script>
         <script type='text/javascript' src='js/iD/format/GeoJSON.js'></script>
         <script type='text/javascript' src='js/iD/format/XML.js'></script>
+
         <script type='text/javascript' src='js/iD/graph/pdata.js'></script>
         <script type='text/javascript' src='js/iD/graph/Node.js'></script>
         <script type='text/javascript' src='js/iD/graph/Relation.js'></script>

js/iD/Connection.js

@@ -27,6 +27,7 @@ iD.Connection = function(graph) {
     }
 
     // <tag k="highway" v="unclassified"/>
+    // { highway: 'classified' }
     function getTags(obj) {
         var tags = {}, tagelems = obj.getElementsByTagName('tag');
         for (var i = 0, l = tagelems.length; i < l; i++) {

js/iD/actions/actions.js

@@ -1,5 +1,11 @@
 iD.actions = {};
 
+// Actions are like 'modes' for the editor. They are entered by bindings to
+// clicks and keypresses, and exited by the same.
+//
+// Actions aim to include a bare minimum of 'business logic' - this is separated
+// into operations.
+
 iD.actions._node = function(ll) {
     return {
         type: 'node',
@@ -172,7 +178,8 @@ iD.actions.Move = {
     exit: function() { }
 };
 
-
+// A controller holds a single action at a time and calls `.enter` and `.exit`
+// to bind and unbind actions.
 iD.controller = function(map) {
     var controller = { action: null };
 

js/iD/actions/operations.js

@@ -1,5 +1,9 @@
 iD.operations = {};
 
+// operations take a map, and arguments that they modify in the map's graph.
+// they use `graph.modify` to do this while keeping a previous version
+// of the graph the same.
+
 iD.operations.addNode = function(map, node) {
     map.graph.modify(function(graph) {
         var o = {};
@@ -20,7 +24,6 @@ iD.operations.startWay = function(map, way) {
 
 iD.operations.remove = function(map, node) {
     map.graph.modify(function(graph) {
-        console.log(node.id);
         return graph.remove(node.id);
     }, 'removed a feature');
     map.update();

js/iD/format/GeoJSON.js

@@ -1,4 +1,4 @@
-iD.GeoJSON = {
+iD.format.GeoJSON = {
     mapping: function(entity) {
         if (this.mappings[entity.type]) {
             return this.mappings[entity.type](entity);

js/iD/format/XML.js

@@ -1,4 +1,4 @@
-iD.XML = {
+iD.format.XML = {
     mapping: function(entity) {
         if (this.mappings[entity.type]) {
             return this.mappings[entity.type](entity);

js/iD/graph/Graph.js

@@ -30,9 +30,11 @@ iD.Graph.prototype = {
         return pois;
     },
 
+    // rewind and fast-forward the graph. these preserve the other modes of the
+    // graph. these attempt to skip over any edits that didn't have an annotation,
+    // like 'invisible edits' and sub-edits.
     undo: function() {
         if (this.prev.length && this.prev[0] !== this.head) {
-            // skip changes without annotations
             for (var idx = this.prev.indexOf(this.head) - 1; idx > 0; idx--) {
                 if (this.annotations[idx]) break;
             }
@@ -40,7 +42,6 @@ iD.Graph.prototype = {
             this.annotation = this.annotations[idx];
         }
     },
-
     redo: function() {
         if (this.prev.length && this.prev[this.prev.length - 1] !== this.head) {
             for (var idx = this.prev.indexOf(this.head) + 1; idx < this.prev.length - 1; idx++) {
@@ -58,6 +59,11 @@ iD.Graph.prototype = {
         }
     },
 
+    // the gist of all operations on the graph: the callback function
+    // receives the current graph and returns a modified graph. the graph
+    // given to the callback is guaranteed to be immutable at one level - the
+    // key -> object mappings. the callback is responsible for keeping objects
+    // in the graph immutable.
     modify: function(callback, annotation) {
         // create a pdata wrapper of current head
         var o = pdata.object(this.head);
@@ -79,6 +85,7 @@ iD.Graph.prototype = {
         this.annotation = this.annotations[this.annotations.length - 1];
     },
 
+    // get all objects that intersect an extent.
     intersects: function(extent) {
         var items = [];
         for (var i in this.head) {

js/iD/renderer/markers.js

@@ -1,5 +1,6 @@
+// an index of tag -> marker image combinations, taken from
+// http://svn.openstreetmap.org/applications/rendering/mapnik/inc/layer-amenity-symbols.xml.inc
 iD._markers = [
-    // http://svn.openstreetmap.org/applications/rendering/mapnik/inc/layer-amenity-symbols.xml.inc
     {
         tags: { aeroway: 'helipad' },
         icon: 'helipad'
@@ -548,6 +549,7 @@ iD._markers = [
     }
 ];
 
+// generate a fast lookup table for marker styling
 iD._markertable = (function(markers) {
     var table = {};
     for (var i = 0; i < markers.length; i++) {

js/iD/renderer/style.js

@@ -1,4 +1,12 @@
 iD.Style = {};
+
+// all styling that is done outside of CSS in iD.
+//
+// Since SVG does not support z-index, we sort roads manually with d3's `sort`
+// and the `waystack` fn.
+// 
+// This also chooses kosher CSS classes for ways, and marker images for POIs
+
 iD.Style.highway_stack = {
     motorway: 0,
     motorway_link: 1,

js/iD/renderer/tiles.js

@@ -2,6 +2,7 @@
 iD.Tiles = function(selection, projection, width, height) {
     var tiles = {};
 
+    // derive the url of a 'quadkey' style tile from a coordinate object
     function tileUrl(coord) {
         var u = '';
         for (var zoom = coord[0]; zoom > 0; zoom--) {
@@ -14,6 +15,8 @@ iD.Tiles = function(selection, projection, width, height) {
         return  'http://ecn.t0.tiles.virtualearth.net/tiles/a' + u + '.jpeg?g=587&mkt=en-gb&n=z';
     }
 
+    // derive the tiles onscreen, remove those offscreen and position tiles
+    // correctly for the currentstate of `projection`
     function redraw() {
         var t = projection.translate(),
             s = projection.scale(),

js/iD/ui/Inspector.js

@@ -26,7 +26,7 @@ iD.Inspector = function(graph) {
                 .text('XML')
                 .on('click', function() {
                     d3.event.stopPropagation();
-                    iD.Util.codeWindow(iD.XML.mapping(graph.fetch(d.id)));
+                    iD.Util.codeWindow(iD.format.XML.mapping(graph.fetch(d.id)));
                 });
 
             head.append('a')
@@ -36,7 +36,7 @@ iD.Inspector = function(graph) {
                 .on('click', function() {
                     d3.event.stopPropagation();
                     iD.Util.codeWindow(JSON.stringify(
-                        iD.GeoJSON.mapping(graph.fetch(d.id)), null, 2));
+                        iD.format.GeoJSON.mapping(graph.fetch(d.id)), null, 2));
                 });
 
             var table = d3.select(this)