Repository: eslint/doctrine (js)

Issue:
Support example caption
According to [usejsdoc's example documentation](http://usejsdoc.org/tags-example.html), it's valid to caption an example tag with `<caption>...</caption>`

```
/**
 * Solves equations of the form a * x = b
 * @example <caption>Example usage of method1.</caption>
 * // returns 2
 * globalNS.method1(5, 10);
 * @returns {Number} Returns the value of x for the equation.
 */
```

Pull request description:
New: parse caption tags in examples into a separate property. Fixes #131

Patch:
diff --git a/lib/doctrine.js b/lib/doctrine.js
index c38830a..c04effa 100644
--- a/lib/doctrine.js
+++ b/lib/doctrine.js
@@ -526,6 +526,22 @@
             return true;
         };
 
+        TagParser.prototype.parseCaption = function parseDescription() {
+            var description = trim(sliceSource(source, index, this._last));
+            var captionStartTag = '<caption>';
+            var captionEndTag = '</caption>';
+            var captionStart = description.indexOf(captionStartTag);
+            var captionEnd = description.indexOf(captionEndTag);
+            if (captionStart >= 0 && captionEnd >= 0) {
+                this._tag.caption = trim(description.substring(
+                    captionStart + captionStartTag.length, captionEnd));
+                this._tag.description = trim(description.substring(captionEnd + captionEndTag.length));
+            } else {
+                this._tag.description = description;
+            }
+            return true;
+        };
+
         TagParser.prototype.parseKind = function parseKind() {
             var kind, kinds;
             kinds = {
@@ -620,6 +636,8 @@
             'class': ['parseType', 'parseNamePathOptional', 'ensureEnd'],
             // Synonym: http://usejsdoc.org/tags-extends.html
             'extends': ['parseType', 'parseNamePathOptional', 'ensureEnd'],
+            // http://usejsdoc.org/tags-example.html
+            'example': ['parseCaption'],
             // http://usejsdoc.org/tags-deprecated.html
             'deprecated': ['parseDescription'],
             // http://usejsdoc.org/tags-global.html
diff --git a/package.json b/package.json
index fb7a3c3..5dd3afa 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "doctrine",
   "description": "JSDoc parser",
-  "homepage": "https://github.com/eslint/doctrine",
+  "homepage": "http://github.com/Constellation/doctrine.html",
   "main": "lib/doctrine.js",
   "version": "0.7.0",
   "engines": {


Test patch:
diff --git a/test/parse.js b/test/parse.js
index 7220af1..576a531 100644
--- a/test/parse.js
+++ b/test/parse.js
@@ -1962,6 +1962,21 @@ describe('optional params', function() {
         res.tags[2].should.have.property('lineNumber', 4);
     });
 
+    it('example caption', function() {
+        var res = doctrine.parse(
+            [
+                "/**",
+                " * @example <caption>hi</caption>",
+                " * f('blah'); // => undefined",
+                " */"
+            ].join('\n'),
+            { unwrap: true, lineNumbers: true }
+        );
+
+        res.tags[0].description.should.eql("f('blah'); // => undefined");
+        res.tags[0].caption.should.eql("hi");
+    });
+
     it('should handle \\r\\n line endings correctly', function() {
         var res = doctrine.parse(
             [