From b465902fa2d3bf47e8f285116ba653ba6ccbfaef Mon Sep 17 00:00:00 2001
From: Tom MacWright <tom@macwright.org>
Date: Sun, 14 Feb 2016 18:41:36 -0500
Subject: [PATCH] Add support for example captions

Fixes #110
---
 lib/flatten.js                            |  2 +-
 lib/output/markdown_ast.js                | 11 +++++++----
 package.json                              |  4 ++--
 test/fixture/_multi-file-input.json       |  6 +++++-
 test/fixture/empty-example.output.json    |  8 ++++++--
 test/fixture/empty-example.output.md      |  2 +-
 test/fixture/empty-example.output.md.json |  3 ++-
 test/fixture/html/nested.input.js         |  2 +-
 test/fixture/html/nested.output.files     |  7 +++++--
 test/fixture/multiexample.output.json     | 12 ++++++++++--
 test/fixture/params.output.json           |  6 +++++-
 test/fixture/simple-two.output.json       |  6 +++++-
 test/fixture/throws.output.json           |  6 +++++-
 test/lib/flatten.js                       |  8 ++++++--
 14 files changed, 61 insertions(+), 22 deletions(-)

diff --git a/lib/flatten.js b/lib/flatten.js
index f43fb39..3b1b65d 100644
--- a/lib/flatten.js
+++ b/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';
diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js
index 52265a6..2412866 100644
--- a/lib/output/markdown_ast.js
+++ b/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) {
diff --git a/package.json b/package.json
index 3a35459..881e94b 100644
--- a/package.json
+++ b/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",
diff --git a/test/fixture/_multi-file-input.json b/test/fixture/_multi-file-input.json
index 0cdfd8a..9303180 100644
--- a/test/fixture/_multi-file-input.json
+++ b/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",
diff --git a/test/fixture/empty-example.output.json b/test/fixture/empty-example.output.json
index 0b57c22..26d3b32 100644
--- a/test/fixture/empty-example.output.json
+++ b/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",
diff --git a/test/fixture/empty-example.output.md b/test/fixture/empty-example.output.md
index 316ad51..865f9af 100644
--- a/test/fixture/empty-example.output.md
+++ b/test/fixture/empty-example.output.md
@@ -5,5 +5,5 @@ This function returns the number plus two.
 **Examples**
 
 ```javascript
-undefined
+
 ```
diff --git a/test/fixture/empty-example.output.md.json b/test/fixture/empty-example.output.md.json
index 1c3b3a5..8a1cff3 100644
--- a/test/fixture/empty-example.output.md.json
+++ b/test/fixture/empty-example.output.md.json
@@ -53,7 +53,8 @@
     },
     {
       "lang": "javascript",
-      "type": "code"
+      "type": "code",
+      "value": ""
     }
   ]
 }
\ No newline at end of file
diff --git a/test/fixture/html/nested.input.js b/test/fixture/html/nested.input.js
index 89e49ed..7fffa3d 100644
--- a/test/fixture/html/nested.input.js
+++ b/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 () {
diff --git a/test/fixture/html/nested.output.files b/test/fixture/html/nested.output.files
index b8894da..0e3b229 100644
--- a/test/fixture/html/nested.output.files
+++ b/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>
diff --git a/test/fixture/multiexample.output.json b/test/fixture/multiexample.output.json
index 97f64bb..87e8512 100644
--- a/test/fixture/multiexample.output.json
+++ b/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": [
       {
diff --git a/test/fixture/params.output.json b/test/fixture/params.output.json
index 2c9be16..306c2c6 100644
--- a/test/fixture/params.output.json
+++ b/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",
diff --git a/test/fixture/simple-two.output.json b/test/fixture/simple-two.output.json
index 220a3c4..fbd2c99 100644
--- a/test/fixture/simple-two.output.json
+++ b/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",
diff --git a/test/fixture/throws.output.json b/test/fixture/throws.output.json
index 0aee145..7ec18c0 100644
--- a/test/fixture/throws.output.json
+++ b/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",
diff --git a/test/lib/flatten.js b/test/lib/flatten.js
index 158dbd4..0abd6ca 100644
--- a/test/lib/flatten.js
+++ b/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 */