Docs: Clarify docs for api.verify (fixes #5101, fixes #5104)

Author: BYK

docs/developer-guide/nodejs-api.md

@@ -60,11 +60,12 @@ var linter = require("eslint").linter;
 The most important method on `linter` is `verify()`, which initiates linting of the given text. This method accepts four arguments:
 
 * `code` - the source code to lint (a string or instance of `SourceCode`).
-* `config` - a configuration object.
-* `options` - (optional) Additional options for this run.
+* `config` - a configuration object that is equivalent to an eslintrc file.
+* `optionsOrFilename` - (optional) Additional options for this run or a string representing the filename to associate with the code being linted.
     * `filename` - (optional) the filename to associate with the source code.
-    * `saveState` - (optional) set to true to maintain the internal state of `linter` after linting (mostly used for testing purposes).
+    * `saveState` - (optional) see below. This will override any value passed as the fourth argument if an options object is used here instead of the filename.
     * `allowInlineConfig` - (optional) set to `false` to disable inline comments from changing eslint rules.
+* `saveState` - (optional) set to true to maintain the internal state of `linter` after linting (mostly used for testing purposes)
 
 You can call `verify()` like this:
 

lib/eslint.js

@@ -641,10 +641,21 @@ module.exports = (function() {
         sourceCode = null;
     };
 
+    /**
+     * Configuration object for the `verify` API. A JS representation of the eslintrc files.
+     * @typedef {Object} ESLintConfig
+     * @param {Object} rules The rule configuration to verify against.
+     * @param {string} [parser] Parser to use when generatig the AST.
+     * @param {Object} [parserOptions] Options for the parsed used.
+     * @param {Object} [settings] Global settings passed to each rule.
+     * @param {Object} [env] The environment to verify in.
+     * @param {Object} [globals] Available globalsto the code.
+     */
+
     /**
      * Verifies the text against the rules specified by the second argument.
      * @param {string|SourceCode} textOrSourceCode The text to parse or a SourceCode object.
-     * @param {Object} config An object whose keys specify the rules to use.
+     * @param {ESLintConfig} config An object whose keys specify the rules to use.
      * @param {(string|Object)} [filenameOrOptions] The optional filename of the file being checked.
      *      If this is not set, the filename will default to '<input>' in the rule context. If
      *      an object, then it has "filename", "saveState", and "allowInlineConfig" properties.