IW: Fix docs strings

lib/carto/renderer.js

@@ -7,11 +7,13 @@ carto.Renderer = function Renderer(env, options) {
     this.options.mapnik_version = this.options.mapnik_version || 'latest';
 };
 
-// Prepare a MSS document (given as an string) into a
-// XML Style fragment (mostly useful for debugging)
-//
-// - @param {String} str the mss contents as a string.
-// - @param {Object} env renderer environment options.
+/**
+ * Prepare a MSS document (given as an string) into a
+ * XML Style fragment (mostly useful for debugging)
+ *
+ * @param {String} data the mss contents as a string.
+ * @param {Object} callback renderer environment options.
+ */
 carto.Renderer.prototype.renderMSS = function render(data, callback) {
     // effects is a container for side-effects, which currently
     // are limited to FontSets.
@@ -60,11 +62,13 @@ carto.Renderer.prototype.renderMSS = function render(data, callback) {
     return callback(null, output.join('\n'));
 };
 
-// Prepare a MML document (given as an object) into a
-// fully-localized XML file ready for Mapnik2 consumption
-//
-// - @param {String} str the JSON file as a string.
-// - @param {Object} env renderer environment options.
+/**
+ * Prepare a MML document (given as an object) into a
+ * fully-localized XML file ready for Mapnik2 consumption
+ *
+ * @param {String} m - the JSON file as a string.
+ * @param {Object} callback - renderer environment options.
+ */
 carto.Renderer.prototype.render = function render(m, callback) {
     // effects is a container for side-effects, which currently
     // are limited to FontSets.
@@ -224,13 +228,14 @@ carto.Renderer.prototype.render = function render(m, callback) {
     return callback(null, output.join('\n'));
 };
 
-// This function currently modifies 'current'
-//
-// @param {Array} the current list of rules
-// @param {Object} definition a Definition object to add to the rules
-// @param {Object} byFilter an object/dictionary of existing filters. This is
-// actually keyed `attachment->filter`
-// @param {Object} env the current environment
+/**
+ * This function currently modifies 'current'
+ * @param {Array}  current  current list of rules
+ * @param {Object} definition a Definition object to add to the rules
+ * @param {Object} byFilter an object/dictionary of existing filters. This is
+ * actually keyed `attachment->filter`
+ * @param {Object} env the current environment
+*/
 function addRules(current, definition, byFilter, env) {
     var newFilters = definition.filters,
         newRules = definition.rules,
@@ -283,16 +288,18 @@ function addRules(current, definition, byFilter, env) {
     return current;
 }
 
-// Apply inherited styles from their ancestors to them.
-//
-// called either once per render (in the case of mss) or per layer
-// (for mml)
-//
-// @param {Object} definitions: a list of definitions objects that contain .rules
-// @param {Object} env the environment
-//
-// result: an array of arrays is returned, in which each array refers to a
-// specific attachment
+/**
+ * Apply inherited styles from their ancestors to them.
+ *
+ * called either once per render (in the case of mss) or per layer
+ * (for mml)
+ *
+ * @param {Object} definitions - a list of definitions objects
+ *   that contain .rules
+ * @param {Object} env - the environment
+ * @return {Array<Array>} an array of arrays is returned,
+ *   in which each array refers to a specific attachment
+ */
 function inheritDefinitions(definitions, env) {
     var inheritTime = +new Date();
     // definitions are ordered by specificity,
@@ -364,16 +371,18 @@ function sortStyles(styles, env) {
     return result;
 }
 
-// Find a rule like Map { background-color: #fff; },
-// if any, and return a list of properties to be inserted
-// into the <Map element of the resulting XML. Translates
-// properties of the mml object at `m` directly into XML
-// properties.
-//
-// - @param {Object} m the mml object.
-// - @param {Array} definitions the output of toList.
-// - @param {Object} env.
-// - @return {String} rendered properties.
+/**
+ * Find a rule like Map { background-color: #fff; },
+ * if any, and return a list of properties to be inserted
+ * into the <Map element of the resulting XML. Translates
+ * properties of the mml object at `m` directly into XML
+ * properties.
+ *
+ * @param {Object} m the mml object.
+ * @param {Array} definitions the output of toList.
+ * @param {Object} env
+ * @return {String} rendered properties.
+ */
 function getMapProperties(m, definitions, env) {
     var rules = {};
     var symbolizers = carto.tree.Reference.data.symbolizers.map;