improve docs

README.md

@@ -1,7 +1,3 @@
-# css-detective
-
-Find all `@import`s by walking the AST (similar to and inspired by [detective](https://github.com/substack/node-detective), but for CSS)
-
 <!-- VDOC.badges travis; standard; npm; coveralls -->
 <!-- DON'T EDIT THIS SECTION (including comments), INSTEAD RE-RUN `vdoc` TO UPDATE -->
 [![Build Status](https://travis-ci.org/vigour-io/css-detective.svg?branch=master)](https://travis-ci.org/vigour-io/css-detective)
@@ -11,71 +7,52 @@ Find all `@import`s by walking the AST (similar to and inspired by [detective](h
 
 <!-- VDOC END -->
 
-# example
-
-## strings
-
-style.css:
-
-``` js
-@import 'a';
-@import 'b';
-@import 'c';
-```
+css-detective
+====
 
-strings.js:
+Find all `@import`s by walking the AST
 
-``` js
-var cssDetective = require('css-detective')
-var fs = require('fs')
+Similar to, and inspired by [detective](https://github.com/substack/node-detective). Uses [postcss](https://npmjs.org/package/postcss) to parse the CSS into an abstract syntax tree (AST), so some level of invalid CSS is supported.
 
-var src = fs.readFileSync(__dirname + '/style.css')
-var imports = cssDetective(src)
-console.dir(imports)
-```
+<!-- VDOC.jsdoc cssDetective -->
+<!-- DON'T EDIT THIS SECTION (including comments), INSTEAD RE-RUN `vdoc` TO UPDATE -->
+#### var strings = cssDetective(src, opts)
+- **src** (*string*) - Same as `src` parameter of [find](#var-found--findsrc-opts)
+- **opts** (*object*) - Same as `opts` parameter of [find](#var-found--findsrc-opts)
 
-output:
+Same as `require('css-detective').find(src, opts).strings`
 
-```
-$ node examples/strings.js
-[ 'a', 'b', 'c' ]
-```
+See `find` below
 
-# methods
+<!-- VDOC END -->
 
 ``` js
 var cssDetective = require('css-detective')
+cssDetective('@import "a";\n@import "b";')
+// ['a', 'b']
 ```
 
-## cssDetective(src, opts)
-
-Give some source body `src`, return an array of all the `@import`s.
-
-The options parameter `opts` is passed along to `cssDetective.find()`.
-
-## var found = cssDetective.find(src, opts)
+<!-- VDOC.jsdoc find -->
+<!-- DON'T EDIT THIS SECTION (including comments), INSTEAD RE-RUN `vdoc` TO UPDATE -->
+#### var found = find(src, [opts])
+- **src** (*string*) - Source css body (anything [postcss](https://npmjs.org/package/postcss) can parse). Can be a string or anything with a `toString` method
+- **[opts]** (*object*) - An object with any of the following options:
 
-Give some source body `src`, return `found` with:
+- + **opts.nodes** (*boolean*) - when `true`, populates `found.nodes`
 
-* `found.strings` - an array of each string found in an `@import`
-* `found.nodes` (when `opts.nodes === true`) - an array of AST nodes for each
-argument found in an `@import`
+- + **opts.parse** (*object*) - options to provide directly to
 
-Optionally:
+ [postcss's `parse` method](https://github.com/postcss/postcss/blob/master/docs/api.md#postcssparsecss-opts)
+- **returns** (*object*) found - returns `found` with:
 
-* `opts.nodes` - when `true`, populate `found.nodes`
-* `opts.isImport(node)` - a function returning whether an AST node is an import
-* `opts.parse` - supply options directly to
-[postcss](https://npmjs.org/package/postcss)
+- + **found.strings** (*array*) - each string found in an `@import`
 
-# install
+- + **found.nodes** (*array*|*undefined*) - AST `@import` nodes found if `opts.nodes === true`, `undefined` otherwise
 
-With [npm](https://npmjs.org) do:
+<!-- VDOC END -->
 
+``` js
+var cssDetective = require('css-detective')
+cssDetective.find('@import "a";\n@import "b";')
+// { strings: ['a', 'b'] }
 ```
-npm install css-detective
-```
-
-# license
-
-ISC

index.js

@@ -3,10 +3,31 @@
 var postcss = require('postcss')
 var unquote = require('./unquote')
 
+/**
+ * @id cssDetective
+ * @function cssDetective
+ * @param src {string} - Same as `src` parameter of [find](#var-found--findsrc-opts)
+ * @param opts {object} - Same as `opts` parameter of [find](#var-found--findsrc-opts)
+ * Same as `require('css-detective').find(src, opts).strings`
+ * See `find` below
+ * @returns strings {array}
+ */
 module.exports = exports = function (src, opts) {
   return exports.find(src, opts).strings
 }
 
+/**
+ * @id find
+ * @function find
+ * @param src {string} - Source css body (anything [postcss](https://npmjs.org/package/postcss) can parse). Can be a string or anything with a `toString` method
+ * @param [opts] {object} - An object with any of the following options:
+ * - + **opts.nodes** (*boolean*) - when `true`, populates `found.nodes`
+ * - + **opts.parse** (*object*) - options to provide directly to
+ [postcss's `parse` method](https://github.com/postcss/postcss/blob/master/docs/api.md#postcssparsecss-opts)
+ * @returns found {object} - returns `found` with:
+ * - + **found.strings** (*array*) - each string found in an `@import`
+ * - + **found.nodes** (*array*|*undefined*) - AST `@import` nodes found if `opts.nodes === true`, `undefined` otherwise
+ */
 exports.find = function (src, opts) {
   if (!opts) {
     opts = {}