Document API

Author: jugglinmike

pages/api.md

@@ -0,0 +1,110 @@
+{ "title": "JSHint API", "url": "/docs/api/", "template": "docs" }
+
+# Application Programming Interface
+
+JSHint exposes a JavaScript API for programmatic access in environments like
+web browsers and [Node.js](https://nodejs.org).
+
+## `JSHINT( source, options, predef )`
+
+Analyze source code for errors and potential problems.
+
+Parameters:
+
+- `source`
+  - Description: The input JavaScript source code
+  - Type: string or an array of strings (each element is interpreted as a
+    newline)
+  - Example: `JSHINT(["'use strict';", "console.log('hello, world!');"]);`
+- `options`
+  - Description: The [linting options](/docs/options/) to use when analyzing
+    the source code
+  - Type: an object whose property names are the desired options to use and
+    whose property values are the configuration values for those properties.
+  - Example: `JSHINT(mySource, { undef: true });`
+- `predef`
+  - Description: variables defined outside of the current file; the behavior of
+    this argument is identical to [the `globals` linting
+    option](/docs/options#globals)
+  - Type: an object whose property names are the global variable identifiers
+    and whose property values control whether each variable should be
+    considered read-only
+  - Example: `JSHINT(mySource, myOptions, { jQuery: false });`
+
+## `JSHINT.errors`
+
+An array of warnings and errors generated by the most recent invocation of
+`JSHINT`.
+
+## `JSHINT.data()`
+
+Generate a report containing details about the most recent invocation of
+`JSHINT`.
+
+For example, the following code:
+
+    var source = [
+      'function goo() {}',
+      'foo = 3;'
+    ];
+    var options = {
+      undef: true
+    };
+    var predef = {
+      foo: false
+    };
+
+    JSHINT(source, options, predef);
+
+    console.log(JSHINT.data());
+
+...will produce the following output:
+
+    {
+      functions: [
+        {
+          name: 'goo',
+          param: undefined,
+          line: 1,
+          character: 14,
+          last: 1,
+          lastcharacter: 18,
+          metrics: {
+            complexity: 1,
+            parameters: 0,
+            statements: 0
+          }
+        }
+      ],
+      options: {
+        undef: true,
+        indent: 4,
+        maxerr: 50
+      },
+      errors: [
+        {
+          id: '(error)',
+          raw: 'Read only.',
+          code: 'W020',
+          evidence: 'foo = 3;',
+          line: 2,
+          character: 1,
+          scope: '(main)',
+          a: undefined,
+          b: undefined,
+          c: undefined,
+          d: undefined,
+          reason: 'Read only.'
+        }
+      ],
+      globals: [
+        'goo',
+        'foo'
+      ],
+      unused: [
+        {
+          name: 'goo',
+          line: 1, character: 10
+        }
+      ]
+    }

pages/docs.md

@@ -7,19 +7,24 @@ The core project consists of a library itself as well as a CLI program distribut
 as a Node module.
 
 More docs: [List of all JSHint options](/docs/options/) · [Command-line
-Interface](/docs/cli/) · [Writing your own reporter](/docs/reporters/) ·
-[FAQ](/docs/faq/)
+Interface](/docs/cli/) · [API](/docs/api/) · [Writing your own
+reporter](/docs/reporters/) · [FAQ](/docs/faq/)
 
 ### Basic usage
 
-The easiest way to use JSHint is to install it as a Node program. To do so,
-simply run the following command in your terminal (flag -g installs JSHint
-globally on your system, omit it if you want to install JSHint in the current
-working directory):
+First, check out [the installation instructions](/install/) for details on
+how to install JSHint in your perferred environment. Both the command line
+executable and the JavaScript API offer unique ways to configure JSHint's
+behaviour. The most common usages are:
 
-    $ npm install jshint -g
+- [As a command-line tool](/docs/cli/) (via [Node.js](https://nodejs.org))
+- [As a JavaScript module](/docs/api/)
 
-After you've done that you should be able to use the `jshint` program.
+Regardless of your preferred environment, you can control JSHint's behavior
+through specifying any number of [linting options](/docs/options/). In
+addition, JSHint will honor any directives declared within the input source
+code--see [the section on in-line directives](#inline-configuration) for more
+information.
 
 ### Configuration
 
@@ -49,6 +54,8 @@ undefined and unused variables and tell JSHint about a global variable named
       "predef": [ "MY_GLOBAL" ]
     }
 
+<a name="inline-configuration"></a>
+
 ### Inline configuration
 
 In addition to using configuration files you can configure JSHint from within your