more comments in new vector code

src/layer/vector/Circle.js

@@ -1,5 +1,6 @@
 /*
  * L.Circle is a circle overlay (with a certain radius in meters).
+ * It's an approximation and starts to diverge from a real circle closer to poles (due to projection distortion)
  */
 
 L.Circle = L.CircleMarker.extend({

src/layer/vector/Path.js

@@ -1,3 +1,6 @@
+/*
+ * L.Path is the base class for all Leaflet vector layers like polygons and circles.
+ */
 
 L.Path = L.Layer.extend({
 
@@ -22,6 +25,7 @@ L.Path = L.Layer.extend({
 		this._renderer = this._map.getRenderer(this);
 		this._renderer._initPath(this);
 
+		// defined in children classes
 		this._project();
 		this._update();
 
@@ -96,6 +100,7 @@ L.Path = L.Layer.extend({
 	},
 
 	_clickTolerance: function () {
+		// used when doing hit detection for Canvas layers
 		return (this.options.stroke ? this.options.weight / 2 : 0) + (L.Browser.touch ? 10 : 0);
 	}
 });

src/layer/vector/Polygon.js

@@ -1,3 +1,6 @@
+/*
+ * L.Polygon implements polygon vector layer (closed polyline with a fill inside).
+ */
 
 L.Polygon = L.Polyline.extend({
 
@@ -9,6 +12,8 @@ L.Polygon = L.Polyline.extend({
 		var i, j, len, p1, p2, f, area, x, y,
 		    points = this._rings[0];
 
+		// polygon centroid algorithm; only uses the first ring if there are multiple
+
 		area = x = y = 0;
 
 		for (i = 0, len = points.length, j = len - 1; i < len; j = i++) {
@@ -41,6 +46,8 @@ L.Polygon = L.Polyline.extend({
 			return;
 		}
 
+		// polygons need a different clipping algorithm so we redefine that
+
 		var bounds = this._renderer._bounds,
 		    w = this.options.weight,
 		    p = new L.Point(w, w);

src/layer/vector/Polyline.js

@@ -1,3 +1,6 @@
+/*
+ * L.Polyline implements polyline vector layer (a set of points connected with lines)
+ */
 
 L.Polyline = L.Path.extend({
 
@@ -39,7 +42,6 @@ L.Polyline = L.Path.extend({
 		return removed;
 	},
 
-	// TODO remove this method?
 	closestLayerPoint: function (p) {
 		var minDistance = Infinity,
 		    minPoint = null,
@@ -72,6 +74,8 @@ L.Polyline = L.Path.extend({
 		    points = this._rings[0],
 		    len = points.length;
 
+		// polyline centroid algorithm; only uses the first ring if there are multiple
+
 		for (i = 0, halfDist = 0; i < len - 1; i++) {
 			halfDist += points[i].distanceTo(points[i + 1]) / 2;
 		}
@@ -96,6 +100,7 @@ L.Polyline = L.Path.extend({
 		return this._bounds;
 	},
 
+	// recursively convert latlngs input into actual LatLng instances; calculate bounds along the way
 	_convertLatLngs: function (latlngs, nested) {
 		var result = [],
 		    flat = this._flat(latlngs);
@@ -116,13 +121,15 @@ L.Polyline = L.Path.extend({
 	},
 
 	_flat: function (latlngs) {
-		return !L.Util.isArray(latlngs[0]) || typeof latlngs[0][0] === 'number';
+		// true if it's a flat array of latlngs; false if nested
+		return !L.Util.isArray(latlngs[0]) || typeof latlngs[0][0] !== 'object';
 	},
 
 	_project: function () {
 		this._rings = [];
 		this._projectLatlngs(this._latlngs, this._rings);
 
+		// project bounds as well to use later for Canvas hit detection/etc.
 		var w = this._clickTolerance(),
 			p = [w, w];
 
@@ -133,7 +140,9 @@ L.Polyline = L.Path.extend({
 		}
 	},
 
+	// recursively turns latlngs into a set of rings with projected coordinates
 	_projectLatlngs: function (latlngs, result) {
+
 		var flat = latlngs[0] instanceof L.LatLng,
 		    len = latlngs.length,
 		    i, ring;
@@ -151,6 +160,7 @@ L.Polyline = L.Path.extend({
 		}
 	},
 
+	// clip polyline by renderer bounds so that we have less to render for performance
 	_clipPoints: function () {
 		if (this.options.noClip) {
 			this._parts = this._rings;
@@ -183,7 +193,7 @@ L.Polyline = L.Path.extend({
 		}
 	},
 
-	// simplify each clipped part of the polyline
+	// simplify each clipped part of the polyline for performance
 	_simplifyPoints: function () {
 		var parts = this._parts,
 			tolerance = this.options.smoothFactor;