Add API docs. Fixes #38

API.md

@@ -0,0 +1,30 @@
+### `validate(str)`
+
+Validate a Mapbox GL Style given as a string of JSON. Returns an array
+that can contain any number of objects representing errors. Each
+object has members `line` (number) and `message` (string).
+
+This expects the style to be given as a string, rather than an object,
+so that it can return accurate line numbers for errors. If you happen to
+have an object, you'll need to use JSON.stringify() to convert it to a string
+first.
+
+
+### Parameters
+
+| parameter | type   | description                   |
+| --------- | ------ | ----------------------------- |
+| `str`     | string | a Mapbox GL Style as a string |
+
+
+### Example
+
+```js
+var fs = require('fs');
+var validate = require('mapbox-gl-style-lint');
+var style = fs.readFileSync('./style.json', 'utf8');
+var errors = validate(style);
+```
+
+
+**Returns** `Array.<Object>`, an array of error objects

README.md

@@ -23,6 +23,8 @@ $ gl-style-validate style.json
 Will validate the given style JSON and print errors to stdout. Provide a
 `--json` flag to get JSON output.
 
+### [API](API.md)
+
 ### Migrations
 
 This repo contains scripts for migrating GL styles of any version to the latest version

lib/validate.js

@@ -5,6 +5,25 @@ var reference = require('mapbox-gl-style-spec/reference/v6');
 var parseCSSColor = require('csscolorparser').parseCSSColor;
 var format = require('util').format;
 
+/**
+ * Validate a Mapbox GL Style given as a string of JSON. Returns an array
+ * that can contain any number of objects representing errors. Each
+ * object has members `line` (number) and `message` (string).
+ *
+ * This expects the style to be given as a string, rather than an object,
+ * so that it can return accurate line numbers for errors. If you happen to
+ * have an object, you'll need to use JSON.stringify() to convert it to a string
+ * first.
+ *
+ * @alias validate
+ * @param {string} str a Mapbox GL Style as a string
+ * @returns {Array<Object>} an array of error objects
+ * @example
+ * var fs = require('fs');
+ * var validate = require('mapbox-gl-style-lint');
+ * var style = fs.readFileSync('./style.json', 'utf8');
+ * var errors = validate(style);
+ */
 module.exports = function(str) {
     var style;
 

package.json

@@ -10,6 +10,7 @@
   },
   "scripts": {
     "test": "jshint lib/*.js migrations/*.js && tape test/*.js test/migrations/*.js",
+    "doc": "dox -r < lib/validate.js | doxme",
     "cov": "istanbul cover ./node_modules/.bin/tape test/*.js test/migrations/*.js && coveralls < ./coverage/lcov.info"
   },
   "repository": {
@@ -18,12 +19,14 @@
   },
   "license": "ISC",
   "devDependencies": {
-    "tape": "^2.12.1",
-    "jshint": "^2.5.0",
+    "coveralls": "~2.10.0",
     "coverify": "~1.0.7",
+    "dox": "^0.6.1",
+    "doxme": "^1.4.2",
     "istanbul": "~0.2.11",
-    "coveralls": "~2.10.0",
-    "mapbox-gl-styles": "git+https://github.com/mapbox/mapbox-gl-styles.git#mb-pages"
+    "jshint": "^2.5.0",
+    "mapbox-gl-styles": "git+https://github.com/mapbox/mapbox-gl-styles.git#mb-pages",
+    "tape": "^2.12.1"
   },
   "dependencies": {
     "csscolorparser": "~1.0.2",