diff --git a/README.md b/README.md
index 99a994f..7c5fc19 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,6 @@ bum
 cowardly
 little
 British
-
 ```
 
 Node.js:
@@ -50,8 +49,6 @@ wordpos.isAdjective('awesome', function(result){
 // true 'awesome'
 ```
 
-See `wordpos_spec.js` for full usage.
-
 ### Options
 
 ```js
@@ -74,7 +71,7 @@ WordPOS.defaults = {
   stopwords: true
 };
 ```
-To override, pass an options hash to the constructor. With the `profile` option, all callbacks receive a second argument that is the execution time in msec of the call.
+To override, pass an options hash to the constructor. With the `profile` option, all callbacks receive a last argument that is the execution time in msec of the call.
 
 ```js
     wordpos = new WordPOS({profile: true});
@@ -87,9 +84,13 @@ To override, pass an options hash to the constructor. With the `profile` option,
 Please note: all API are async since the underlying WordNet library is async. WordPOS is a subclass of natural's [WordNet class](https://github.com/NaturalNode/natural#wordnet) and inherits all its methods.
 
 
-### getX()...
+### getPOS(text, callback)
+### getNouns(text, callback)
+### getVerbs(text, callback)
+### getAdjectives(text, callback)
+### getAdverbs(text, callback)
 
-Get POS from text.
+Get part-of-speech from text.  `callback(results)` receives and array of words for specified POS, or a hash for `getPOS`:
 
 ```
 wordpos.getPOS(text, callback) -- callback receives a result object:
@@ -101,23 +102,15 @@ wordpos.getPOS(text, callback) -- callback receives a result object:
       rest:[]         Array of text words that are not in dict or could not be categorized as a POS
     }
     Note: a word may appear in multiple POS (eg, 'great' is both a noun and an adjective)
-
-wordpos.getNouns(text, callback) -- callback receives an array of nouns in text
-
-wordpos.getVerbs(text, callback) -- callback receives an array of verbs in text
-
-wordpos.getAdjectives(text, callback) -- callback receives an array of adjectives in text
-
-wordpos.getAdverbs(text, callback) -- callback receives an array of adverbs in text
 ```
 
 If you're only interested in a certain POS (say, adjectives), using the particular getX() is faster
 than getPOS() which looks up the word in all index files. [stopwords] (https://github.com/NaturalNode/natural/blob/master/lib/natural/util/stopwords.js)
 are stripped out from text before lookup.
 
-If text is an *array*, all words are looked-up -- no deduplication, stopword filter or tokenization is applied.
+If `text` is an *array*, all words are looked-up -- no deduplication, stopword filter or tokenization is applied.
 
-getX() functions return the number of parsed words that will be looked up (less duplicates and stopwords).
+getX() functions (immediately) return the number of parsed words that *will be* looked up (less duplicates and stopwords).
 
 Example:
 
@@ -136,24 +129,15 @@ wordpos.getPOS('The angry bear chased the frightened little squirrel.', console.
   }
 
 ```
-This has no relation to correct grammer of given sentence, where here only 'bear' and 'squirrel'
+This has no relation to correct grammar of given sentence, where here only 'bear' and 'squirrel'
 would be considered nouns. 
 
-### isX()...
+### isNoun(word, callback)
+### isVerb(word, callback)
+### isAdjective(word, callback)
+### isAdverb(word, callback)
 
-Determine if a word is a particular POS.
-
-```
-wordpos.isNoun(word, callback) -- callback receives true/false if word is a noun.
-
-wordpos.isVerb(word, callback) -- callback receives true/false if word is a verb.
-
-wordpos.isAdjective(word, callback) -- callback receives true/false if word is an adjective.
-
-wordpos.isAdverb(word, callback) -- callback receives true/false if word is an adverb.
-```
-
-isX() methods return the looked-up word as the second argument to the callback.
+Determine if a word is a particular POS.  `callback(result, word)` receives true/false as first argument and the looked-up word as the second argument.
 
 Examples:
 
@@ -171,22 +155,13 @@ wordpos.isAdverb('fishly', console.log);
 // false 'fishly'
 ```
 
-### lookupX()...
+### lookupNoun(word, callback)
+### lookupVerb(word, callback)
+### lookupAdjective(word, callback)
+### lookupAdverb(word, callback)
 
 These calls are similar to natural's [lookup()](https://github.com/NaturalNode/natural#wordnet) call, except they can be faster if you
-already know the POS of the word.
-
-```
-wordpos.lookupNoun(word, callback) -- callback receives array of lookup objects for a noun
-
-wordpos.lookupVerb(word, callback) -- callback receives array of lookup objects for a verb
-
-wordpos.lookupAdjective(word, callback) -- callback receives array of lookup objects for an adjective
-
-wordpos.lookupAdverb(word, callback) -- callback receives array of lookup objects for an adverb
-```
-
-lookupX() methods return the looked-up word as the second argument to the callback.
+already know the POS of the word.  Signature of the callback is `callback(result, word)` where `result` is an *array* of lookup object(s). 
 
 Example:
 
@@ -207,7 +182,6 @@ oul beneath"- Melville; "Westminster Hall\'s awing majesty, so vast, so high, so
 ```
 In this case only one lookup was found.  But there could be several.
 
-
 Or use WordNet's inherited method:
 
 ```js
@@ -215,26 +189,16 @@ wordpos.lookup('great', console.log);
 // ...
 ```
 
-### randX()
+### rand(options, callback)
+### randNoun(options, callback)
+### randVerb(options, callback)
+### randAdjective(options, callback)
+### randAdverb(options, callback)
 
-Get random word(s).  (Introduced in version 0.1.10)
-
-```js
-wordpos.rand(options, callback)
-
-wordpos.randNoun(options, callback)
-
-wordpos.randVerb(options, callback)
-
-wordpos.randAdjective(options, callback)
-
-wordpos.randAdverb(options, callback)
-```
-Callback receives array of random words and the `startsWith` option.
-`options`, if given, is:
+Get random word(s).  (Introduced in version 0.1.10)  `callback(results, startsWith)` receives array of random words and the `startsWith` option, if one was  given. `options`, if given, is:
 ```
 {
-  startsWith : <string> -- get random words starting with string
+  startsWith : <string> -- get random words starting with this
   count : <number> -- number of words to return (default = 1)
 }
 ```
@@ -256,19 +220,19 @@ wordpos.rand({starsWith: 'zzz'}, console.log)
 // [] 'zzz'
 ```
 
-Note on performance: random lookups could involve heavy disk reads.  It is better to use the 'count' option to get words
+**Note on performance**: random lookups could involve heavy disk reads.  It is better to use the `count` option to get words
 in batches.  This may benefit from the cached reads of similarly keyed entries as well as shared open/close of the index files.
 
-Getting random POS (randNoun, etc.) is generally faster than rand(), which may look at multiple POS files until 'count' requirement
+Getting random POS (`randNoun()`, etc.) is generally faster than `rand()`, which may look at multiple POS files until `count` requirement
 is met.
 
 
 ### Other methods/properties
 
 ```
-WordPOS.WNdb -- access to the WNdb object
+WordPOS.WNdb -- access to the [WNdb](https://github.com/moos/WNdb) object containing the dictionary & index files
 
-WordPOS.natural -- access to underlying 'natural' module
+WordPOS.natural -- access to underlying [natural](http://github.com/NaturalNode/natural) module
 
 wordpos.parse(str) -- returns tokenized array of words, less duplicates and stopwords.  
    This method is called on all getX() calls internally.
@@ -320,7 +284,7 @@ done in 1375 msecs
 
 ## Changes
 
-v0.1.11 
+v0.1.12 
 - fix stopwords not getting excluded when running with CLI
 - added 'stopwords' CLI *command* to show list of stopwords
 - CLI *option* --stopword now renamed to --withStopwords