Improve internal documentation

lib/client.js

@@ -28,6 +28,8 @@ var MapboxDatasets = require('./services/datasets');
  */
 var MapboxClient = makeClient('MapboxClient');
 
+// Combine all client APIs into one API for when people require()
+// the main mapbox-sdk-js library.
 xtend(MapboxClient.prototype,
   MapboxGeocoder.prototype,
   MapboxSurface.prototype,

lib/constants.js

@@ -1,5 +1,8 @@
 var compile = require('es6-template-strings/compile');
 
+// We keep all of the constants that declare endpoints in one
+// place, so that we could concievably update this for API layout
+// revisions.
 module.exports.DEFAULT_ENDPOINT = 'https://api.mapbox.com';
 module.exports.API_GEOCODER_FORWARD = compile('${endpoint}/v4/geocode/${dataset}/${encodeURIComponent(forwardQuery)}.json?${query}');
 module.exports.API_GEOCODER_REVERSE = compile('${endpoint}/v4/geocode/${dataset}/${location.longitude},${location.latitude}.json?${query}');

lib/format_points.js

@@ -2,6 +2,16 @@
 
 var invariant = require('invariant');
 
+/**
+ * Format waypionts in a way that's friendly to the directions and surface
+ * API: comma-separated latitude, longitude pairs with semicolons between
+ * them.
+ * @private
+ * @param {Array<Object>} waypoints array of objects with latitude and longitude
+ * properties
+ * @returns {string} formatted points
+ * @throws {Error} if the input is invalid
+ */
 function formatPoints(waypoints) {
   return waypoints.map(function(location) {
     invariant(typeof location.latitude === 'number' &&

lib/get_user.js

@@ -1,5 +1,15 @@
 'use strict';
 
+/**
+ * Access tokens actually are data, and using them we can derive
+ * a user's username. This method attempts to do just that,
+ * decoding the part of the token after the first `.` into
+ * a username.
+ *
+ * @private
+ * @param {string} token an access token
+ * @return {string} username
+ */
 function getUser(token) {
   var data = token.split('.')[1];
   if (!data) return null;

lib/make_service.js

@@ -4,6 +4,17 @@ var invariant = require('invariant');
 var constants = require('./constants');
 var getUser = require('./get_user');
 
+/**
+ * Services all have the same constructor pattern: you initialize them
+ * with an access token and options, and they validate those arguments
+ * in a predictable way. This is a constructor-generator that makes
+ * it possible to require each service's API individually.
+ *
+ * @private
+ * @param {string} name the name of the Mapbox API this class will access:
+ * this is set to the name of the function so it will show up in tracebacks
+ * @returns {Function} constructor function
+ */
 function makeService(name) {
 
   function service(accessToken, options) {