Document, test, and extend static $.text method (#855)

* Document and test static `text` method

* Extend `$.text()` to operate on current root

Update `$.root` to return the rendered text content of the current root
element when no argument is specified. This increases API parity with
the existing static methods `$.html` and``$.xml`.

This change technically breaks backwards compatability, but the previous
behavior was undocumented and untested.

Author: jugglinmike

Readme.md

@@ -822,6 +822,21 @@ $.xml()
 //=>  <media:thumbnail url="http://www.foo.com/keyframe.jpg" width="75" height="50" time="12:05:01.123"/>
 ```
 
+You may also render the text content of a Cheerio object using the `text` static method:
+
+```js
+$ = cheerio.load('This is <em>content</em>.')
+$.text()
+//=> This is content.
+```
+
+The method may be called on the Cheerio module itself--be sure to pass a collection of nodes!
+
+```js
+$ = cheerio.load('<div>This is <em>content</em>.</div>')
+cheerio.text($('div'))
+//=> This is content.
+```
 
 ### Miscellaneous
 DOM element methods that don't fit anywhere else

lib/static.js

@@ -109,7 +109,9 @@ exports.xml = function(dom) {
  */
 
 exports.text = function(elems) {
-  if (!elems) return '';
+  if (!elems) {
+    elems = this.root();
+  }
 
   var ret = '',
       len = elems.length,

test/api/utils.js

@@ -35,6 +35,28 @@ describe('cheerio', function() {
   });
 
 
+  describe('.text', function() {
+    it('(cheerio object) : should return the text contents of the specified elements', function() {
+      var $ = cheerio.load('<a>This is <em>content</em>.</a>');
+      expect($.text($('a'))).to.equal('This is content.');
+    });
+
+    it('(cheerio object) : should omit comment nodes', function() {
+      var $ = cheerio.load('<a>This is <!-- a comment --> not a comment.</a>');
+      expect($.text($('a'))).to.equal('This is  not a comment.');
+    });
+
+    it('(cheerio object) : should include text contents of children recursively', function() {
+      var $ = cheerio.load('<a>This is <div>a child with <span>another child and <!-- a comment --> not a comment</span> followed by <em>one last child</em> and some final</div> text.</a>');
+      expect($.text($('a'))).to.equal('This is a child with another child and  not a comment followed by one last child and some final text.');
+    });
+
+    it('() : should return the rendered text content of the root', function() {
+      var $ = cheerio.load('<a>This is <div>a child with <span>another child and <!-- a comment --> not a comment</span> followed by <em>one last child</em> and some final</div> text.</a>');
+      expect($.text()).to.equal('This is a child with another child and  not a comment followed by one last child and some final text.');
+    });
+  });
+
 
   describe('.load', function() {