Permalink
Browse files

Moved docs from jshint.js to README and re-aligned the code.

We don't need docs in three places (site, source and README) so I
moved them from source to README. I also realigned broken spaces
in options declarations and removed `/*members ... */` block because
it adds little value and is super annoying to maintain.
  • Loading branch information...
valueof committed Oct 29, 2012
1 parent 05134c1 commit 0e096ee4a31c3625d46daf2dd38865b31035774d
Showing with 579 additions and 652 deletions.
  1. +152 −33 README.md
  2. +427 −619 src/stable/jshint.js
View
185 README.md
@@ -13,21 +13,23 @@ We believe that static code analysis programs—as well as other code quality
tools—are important and beneficial to the JavaScript community and, thus,
should not alienate their users.
-For general usage information, visit our website: [http://jshint.com/](http://jshint.com/).
+For general usage information, visit our website:
+[http://jshint.com/](http://jshint.com/).
Reporting a bug
---------------
-To report a bug simply create a [new GitHub Issue](https://github.com/jshint/jshint/issues/new) and
-describe your problem or suggestion. We welcome all kind of feedback regarding JSHint including but
-not limited to:
+To report a bug simply create a
+[new GitHub Issue](https://github.com/jshint/jshint/issues/new) and describe
+your problem or suggestion. We welcome all kind of feedback regarding
+JSHint including but not limited to:
* When JSHint doesn't work as expected
* When JSHint complains about valid JavaScript code that works in all browsers
* When you simply want a new option or feature
-Before reporting a bug look around to see if there are any open or closed tickets that
-cover your issue. And remember the wisdom: pull request > bug report > tweet.
+Before reporting a bug look around to see if there are any open or closed tickets
+that cover your issue. And remember the wisdom: pull request > bug report > tweet.
Installation
------------
@@ -36,8 +38,8 @@ You can install JSHint via NPM:
npm install jshint -g
-We also provide platform wrappers for Rhino, JavaScriptCore and Windows Script Host. To
-use them, clone this repo and run our build command:
+We also provide platform wrappers for Rhino, JavaScriptCore and Windows Script
+Host. To use them, clone this repo and run our build command:
node make.js
@@ -50,7 +52,8 @@ You can also require JSHint itself as a module.
var jshint = require('jshint');
-Note: If you are using npm v1.x be sure to install jshint locally (without the -g flag) or link it globally.
+Note: If you are using npm v1.x be sure to install jshint locally (without the -g
+flag) or link it globally.
Custom Reporters
----------------
@@ -70,65 +73,181 @@ Show additional non-error data generated by jshint (unused globals etc).
Configuration Options
---------------------
-**Note:** This behavior described below is very different from versions prior to `0.6`.
+**Note:** This behavior described below is very different from versions
+prior to `0.6`.
-The CLI uses the default options that come with JSHint.
+The CLI uses the default options that come with JSHint. Only one extra
+option is unique to the CLI version of JSHint: `globals` allows you to
+define an object of globals that get ignored for every file.
-Only one extra option is unique to node-jshint: `globals`
-allows you to define an object of globals that get ignored for every file.
-To see an example you can look at how whitelisted globals are defined
-in the [jshint code](https://github.com/jshint/jshint/blob/c047ea1b01097fcc220fcd1a55c41f67ae2e6e81/jshint.js#L556)
-
-To have your own configuration apply, there are several methods you can use:
+To have your own configuration apply, there are several methods you can
+use:
### Specify Manually
-Setting the `--config=/path/to/your/config` command line option to specify your own configuration file outside of the directory tree for your project.
+Setting the `--config=/path/to/your/config` command line option to specify
+your own configuration file outside of the directory tree for your project.
### Within your Project's Directory Tree
-When the CLI is called, and a configuration file isn't specified already, `node-jshint` will attempt to locate one for you starting in `pwd`. (or "present working directory") If this does not yield a `.jshintrc` file, it will move one level up (`..`) the directory tree all the way up to the filesystem root. If a file is found, it stops immediately and uses that set of configuration.
+When the CLI is called, and a configuration file isn't specified already,
+`node-jshint` will attempt to locate one for you starting in `pwd`. (or
+"present working directory") If this does not yield a `.jshintrc` file,
+it will move one level up (`..`) the directory tree all the way up to
+the filesystem root. If a file is found, it stops immediately and uses
+that set of configuration.
-This setup allows you to set up **one** configuration file for your entire project. (place it in the root folder) As long as you run `jshint` from anywhere within your project directory tree, the same configuration file will be used.
+This setup allows you to set up **one** configuration file for your entire
+project. (place it in the root folder) As long as you run `jshint` from
+anywhere within your project directory tree, the same configuration file
+will be used.
### Home Directory
-If all the methods above do not yield a `.jshintrc` to use, the last place that will be checked is your user's `$HOME` directory.
+If all the methods above do not yield a `.jshintrc` to use, the last place
+that will be checked is your user's `$HOME` directory.
## File Extensions
-Default extension for files is ".js". If you want to use JSHint with other file extensions (.json), you need to pass this extra extension as an option :
+Default extension for files is ".js". If you want to use JSHint with other
+file extensions (.json), you need to pass this extra extension as an
+option:
--extra-ext .json
## Ignoring Files and Directories
-If there is a .jshintignore file in your project's directory tree, (also provided you run `jshint` from within your project's directory) then any directories or files specified will be skipped over. (behaves just like a `.gitignore` file)
+If there is a .jshintignore file in your project's directory tree, (also
+provided you run `jshint` from within your project's directory) then any
+directories or files specified will be skipped over. (behaves just like
+a `.gitignore` file)
+
+**Note:** Pattern matching uses minimatch, with the nocase
+[option](https://github.com/isaacs/minimatch). When there is no match,
+it performs a left side match (when no forward slashes present and path
+is a directory).
+
+Using JSHint as a library
+-------------------------
+
+It is easy to use JSHint as a JavaScript library. Just install the package
+with NPM and, in your code, import a global `JSHINT` function:
+
+ var JSHINT = require("jshint").JSHINT;
+
+This function takes two parameters. The first parameter is either a string
+or an array of strings. If it is a string, it will be split on '\n' or
+'\r'. If it is an array of strings, it is assumed that each string
+represents one line. The source can be a JavaScript text or a JSON text.
+
+The second parameter is an optional object of options which control the
+operation of JSHINT. Most of the options are booleans: they are all
+optional and have a default value of false.
+
+The third parameter is an object of global variables, with keys as names
+and a boolean value to determine if they are assignable.
+
+If it checks out, JSHINT returns true. Otherwise, it returns false.
+
+If false, you can inspect JSHINT.errors to find out the problems.
+JSHINT.errors is an array of objects containing these members:
+
+ {
+ line : The line (relative to 1) at which the lint was found
+ character : The character (relative to 1) at which the lint was found
+ reason : The problem
+ evidence : The text line in which the problem occured
+ scope : The scope of the problem.
+ raw : The raw message before the details were inserted
+ a : The first detail
+ b : The second detail
+ c : The third detail
+ d : The fourth detail
+ }
+
+If a fatal error was found, a null will be the last element of the
+JSHINT.errors array.
+
+You can request a data structure which contains JSHint's results.
+
+ var myData = JSHINT.data();
+
+It returns a structure with this form:
+
+ {
+ errors: [
+ {
+ line : NUMBER,
+ character : NUMBER,
+ reason : STRING,
+ evidence : STRING
+ }
+ ],
+ functions: [
+ name : STRING,
+ line : NUMBER,
+ character : NUMBER,
+ last : NUMBER,
+ lastcharacter: NUMBER,
+ param : [ STRING ],
+ closure : [ STRING ],
+ var : [ STRING ],
+ exception : [ STRING ],
+ outer : [ STRING ],
+ unused : [ STRING ],
+ global : [ STRING ],
+ label : [ STRING ]
+ ],
+ globals: [
+ STRING
+ ],
+ member: {
+ STRING: NUMBER
+ },
+ unused: [
+ {
+ name : STRING,
+ line : NUMBER
+ }
+ ],
+ implieds: [
+ {
+ name: STRING,
+ line: NUMBER
+ }
+ ],
+ urls: [
+ STRING
+ ],
+ json: BOOLEAN
+ }
+
+Empty array will not be included.
-**Note:** Pattern matching uses minimatch, with the nocase [option](https://github.com/isaacs/minimatch). When there is no match, it performs a left side match (when no forward slashes present and path is a directory).
FAQ
---
#### How do I turn off "mixed tabs and spaces" warning?
-If you're using so-called [smart tabs](http://www.emacswiki.org/SmartTabs) then
-we have an option `smarttabs` for you. Otherwise, your solution is to run JSHint with
-a custom reporter that discards any warnings you don't like. For example, this [example
-reporter](https://gist.github.com/3885619) discards all warnings about mixed tabs and
-spaces.
+If you're using so-called [smart tabs](http://www.emacswiki.org/SmartTabs)
+then we have an option `smarttabs` for you. Otherwise, your solution is to
+run JSHint with a custom reporter that discards any warnings you don't like.
+For example, this [example reporter](https://gist.github.com/3885619)
+discards all warnings about mixed tabs and spaces.
Contributing
------------
-Look for a file named `CONTRIBUTING.md` in this repository. It contains our contributing
-guidelines. We also have [a mailing list](http://groups.google.com/group/jshint/).
+Look for a file named `CONTRIBUTING.md` in this repository. It contains our
+contributing guidelines. We also have
+[a mailing list](http://groups.google.com/group/jshint/).
License
-------
-JSHint is distributed under the MIT License. One file and one file only (src/stable/jshint.js) is
-distributed under the slightly modified MIT License.
+JSHint is distributed under the MIT License. One file and one file only
+(src/stable/jshint.js) is distributed under the slightly modified MIT License.
Attribution
-----------
Oops, something went wrong.

0 comments on commit 0e096ee

Please sign in to comment.