Add support for example captions

Fixes #110

Author: tmcw

lib/flatten.js

@@ -80,7 +80,7 @@ var flatteners = {
     if (!result.examples) {
       result.examples = [];
     }
-    result.examples.push(tag.description);
+    result.examples.push(tag);
   },
   'global': function (result) {
     result.scope = 'global';

lib/output/markdown_ast.js

@@ -83,10 +83,13 @@ function commentsToAST(comments, opts, callback) {
 
     function examplesSection(comment) {
       return !!comment.examples && [u('strong', [u('text', 'Examples')])]
-        .concat(comment.examples.map(function (example) {
-          language = hljsOptions.highlightAuto ? hljs.highlightAuto(example).language : 'javascript';
-          return u('code', { lang: language }, example);
-        }));
+        .concat(comment.examples.reduce(function (memo, example) {
+          language = hljsOptions.highlightAuto ?
+            hljs.highlightAuto(example.description).language : 'javascript';
+          return memo.concat(example.caption ?
+            [u('paragraph', [u('emphasis', [u('text', example.caption)])])] :
+            []).concat([u('code', { lang: language }, example.description)]);
+        }, []));
     }
 
     function returnsSection(comment) {

package.json

@@ -20,8 +20,8 @@
     "concat-stream": "^1.5.0",
     "debounce": "^1.0.0",
     "disparity": "^2.0.0",
-    "doctrine": "^0.7.1",
-    "documentation-theme-default": "2.2.3",
+    "doctrine": "^1.1.0",
+    "documentation-theme-default": "3.0.0-beta",
     "documentation-theme-utils": "^1.2.1",
     "events": "^1.1.0",
     "extend": "^3.0.0",

test/fixture/_multi-file-input.json

@@ -75,7 +75,11 @@
       }
     ],
     "examples": [
-      "var result = returnTwo(4);\n// result is 6"
+      {
+        "title": "example",
+        "description": "var result = returnTwo(4);\n// result is 6",
+        "lineNumber": 5
+      }
     ],
     "name": "returnTwo",
     "kind": "function",

test/fixture/empty-example.output.json

@@ -4,7 +4,7 @@
     "tags": [
       {
         "title": "example",
-        "description": null,
+        "description": "",
         "lineNumber": 3
       }
     ],
@@ -33,7 +33,11 @@
     },
     "errors": [],
     "examples": [
-      null
+      {
+        "title": "example",
+        "description": "",
+        "lineNumber": 3
+      }
     ],
     "name": "returnTwo",
     "kind": "function",

test/fixture/empty-example.output.md

@@ -5,5 +5,5 @@ This function returns the number plus two.
 **Examples**
 
 ```javascript
-undefined
+
 ```

test/fixture/empty-example.output.md.json

@@ -53,7 +53,8 @@
     },
     {
       "lang": "javascript",
-      "type": "code"
+      "type": "code",
+      "value": ""
     }
   ]
 }

test/fixture/html/nested.input.js

@@ -11,7 +11,7 @@ function Klass(foo) {
 /**
  * Get this Klass's foo
  * @returns {Number} foo
- * @example
+ * @example <caption>this shows you how to getFoo</caption>
  * foo.getFoo();
  */
 Klass.prototype.getFoo = function () {

test/fixture/html/nested.output.files

@@ -1851,7 +1851,8 @@ like a <a href="#Klass">klass</a></p>
 
       </div>
     <h4>Examples</h4>
-<pre class='overflow-auto'><span class="hljs-keyword">var</span> k = <span class="hljs-keyword">new</span> Klass();
+
+    <pre class='overflow-auto'><span class="hljs-keyword">var</span> k = <span class="hljs-keyword">new</span> Klass();
 k.isArrayOfBuffers();</pre>
 </section>
           </div>
@@ -2069,7 +2070,9 @@ the referenced class type</p>
 
       </div>
     <h4>Examples</h4>
-<pre class='overflow-auto'>foo.getFoo();</pre>
+<p><p>this shows you how to getFoo</p>
+</p>
+    <pre class='overflow-auto'>foo.getFoo();</pre>
 </section>
           </div>
         </div>

test/fixture/multiexample.output.json

@@ -90,8 +90,16 @@
       }
     ],
     "examples": [
-      "foo(1);",
-      "foo(2);"
+      {
+        "title": "example",
+        "description": "foo(1);",
+        "lineNumber": 3
+      },
+      {
+        "title": "example",
+        "description": "foo(2);",
+        "lineNumber": 5
+      }
     ],
     "throws": [
       {

test/fixture/params.output.json

@@ -149,7 +149,11 @@
       }
     ],
     "examples": [
-      "var address = new Address6('2001::/32');"
+      {
+        "title": "example",
+        "description": "var address = new Address6('2001::/32');",
+        "lineNumber": 9
+      }
     ],
     "name": "Address6",
     "kind": "class",

test/fixture/simple-two.output.json

@@ -75,7 +75,11 @@
       }
     ],
     "examples": [
-      "var result = returnTwo(4);\n// result is 6"
+      {
+        "title": "example",
+        "description": "var result = returnTwo(4);\n// result is 6",
+        "lineNumber": 5
+      }
     ],
     "name": "returnTwo",
     "kind": "function",

test/fixture/throws.output.json

@@ -95,7 +95,11 @@
       }
     ],
     "examples": [
-      "var result = returnTwo(4);\n// result is 6"
+      {
+        "title": "example",
+        "description": "var result = returnTwo(4);\n// result is 6",
+        "lineNumber": 6
+      }
     ],
     "name": "returnTwo",
     "kind": "function",

test/lib/flatten.js

@@ -43,9 +43,13 @@ test('flatten', function (t) {
     /** @returns {number} test */
   })[0].returns[0].description, 'test', 'returns');
 
-  t.equal(evaluate(function () {
+  t.deepEqual(evaluate(function () {
     /** @example test */
-  })[0].examples[0], 'test', 'example');
+  })[0].examples[0], {
+    lineNumber: 0,
+    title: 'example',
+    description: 'test'
+  }, 'example');
 
   t.equal(evaluate(function () {
     /** @throws {Object} exception */