jsdoc-plugin-strip-outer-iife/README.md

JSDoc plugin to filter out root-level IIFE before processing

# NAME

jsdoc-plugin-strip-outer-iife - JSDoc plugin to filter out root-level [IIFE][] before processing

# INSTALL

    mkdir node_modules
    npm install jsdoc-plugin-strip-outer-iife
    cp node_modules/jsdoc-plugin-strip-outer-iife/strip-outer-iife.js node_modules/jsdoc/plugins/
    # create jsdoc.conf.json mentioning this plugin, see below

# JSDoc configuration

Sample JSDoc configuration file, e.g. jsdoc.conf.json

```json
{ "plugins": [ "plugins/strip-outer-iife.js" ] }
```

# RUN

    jsdoc --configure jsdoc.conf.json inputfile.js

# DESCRIPTION

This is a plugin for [jsdoc][] using the [jsdoc-plugins][] system to filter
source code before it's seen by the main JSDoc parser to remove the common
root-level [IIFE][]'s.  The intent of this plugin is to:
   * Be harmless in case it doesn't understand your content.
   * Allow comments and whitespace before your root-level IIFE.
   * Ignore any and all IIFE's in the body.
   * Allow anything after the close of the root-level IIFE.
   * Only consider IIFE's that start at the beginning of a line, without
     whitespace.
   * Only consider IIFE's that end at the beginning of a line, without
     whitespace.

# EXAMPLES

All of these should get removed:

## Basic inner
```javascript
(function(){
    // Whatever is in here gets saved.
}());
```

## Basic outer
```javascript
(function(){
    // Whatever is in here gets saved.
})();
```

## Browser window
```javascript
(function(){
    // Whatever is in here gets saved.
})(window);
```

## CoffeeScript
```javascript
(function(){
    // Whatever is in here gets saved.
}).call(this);
```
## Common inner
```javascript
/**
 * It's okay to have comments here, these get preserved
 */
// So do single line comments like this
(function(){
    // Whatever is in here gets saved.
}());
// It's also okay to have comments here -- also preserved
```

# LICENSE

This module is licensed under [CC0][], a kind of internationally-aware "public 
domain" license, or more properly said: a declaration of my affirmative intent 
to waive the rights normally reserved under copyright law.  You're free to 
copy, modify, sell for profit, etc, without any need to contact me, give me 
attribution, reproduce the license text, etc.  See [LICENSE][] for the full 
license text.

# TODO

# Why not use this module

   * Not using a real JavaScript parser to modify the input stream, only
     regular expressions.
   * Doesn't use the JSDoc plugin style (yet).
   * Not the right way to fix the problem, see [jsdoc-issue-456][]

[jsdoc-issue-456]: https://github.com/jsdoc3/jsdoc/issues/456
[jsdoc-plugins]: https://github.com/jsdoc3/jsdoc/blob/master/plugins/README.md
[jsdoc]: https://github.com/jsdoc3/jsdoc
[CC0]: http://creativecommons.org/publicdomain/zero/1.0/legalcode
[LICENSE]: https://raw.github.com/boba1l0s2k9/jsdoc-plugin-strip-outer-iife/master/LICENSE
[IIFE]: http://benalman.com/news/2010/11/immediately-invoked-function-expression/