Clean up @example parsing and expand tests - back to 100% coverage

Author: jfirebaugh

lib/lint.js

@@ -34,15 +34,6 @@ function lintComments(comment) {
       }
     }
 
-    function checkEmptyExample(tag) {
-      if (!tag.description) {
-        comment.errors.push({
-          message: 'empty example is found',
-          commentLineNumber: tag.lineNumber
-        });
-      }
-    }
-
     function checkCanonical(type) {
       if (type.type === 'NameExpression') {
         nameInvariant(type.name);
@@ -60,10 +51,6 @@ function lintComments(comment) {
     if (tag.title === 'param' && tag.type) {
       checkCanonical(tag.type);
     }
-
-    if (tag.title === 'example') {
-      checkEmptyExample(tag);
-    }
   });
   return comment;
 }

lib/parse.js

@@ -30,10 +30,27 @@ var flatteners = {
   'emits': synonym('fires'),
   'event': flattenDescription,
   'example': function (result, tag) {
+    if (!tag.description) {
+      result.errors.push({
+        message: '@example without code',
+        commentLineNumber: tag.lineNumber
+      });
+      return;
+    }
+
     if (!result.examples) {
       result.examples = [];
     }
-    result.examples.push(tag);
+
+    var example = {
+      description: tag.description
+    };
+
+    if (tag.caption) {
+      example.caption = tag.caption;
+    }
+
+    result.examples.push(example);
   },
   'exception': synonym('throws'),
   'extends': synonym('augments'),

test/fixture/_multi-file-input.json

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

test/fixture/empty-example.output.json

@@ -31,12 +31,10 @@
       },
       "code": "/**\n * This function returns the number plus two.\n *\n * @example\n */\nfunction returnTwo() {\n  return a + 2;\n}\n"
     },
-    "errors": [],
-    "examples": [
+    "errors": [
       {
-        "title": "example",
-        "description": "",
-        "lineNumber": 3
+        "message": "@example without code",
+        "commentLineNumber": 3
       }
     ],
     "name": "returnTwo",

test/fixture/empty-example.output.md

@@ -1,9 +1,3 @@
 # returnTwo
 
 This function returns the number plus two.
-
-**Examples**
-
-```javascript
-
-```

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

@@ -41,20 +41,6 @@
         },
         "indent": []
       }
-    },
-    {
-      "type": "strong",
-      "children": [
-        {
-          "type": "text",
-          "value": "Examples"
-        }
-      ]
-    },
-    {
-      "lang": "javascript",
-      "type": "code",
-      "value": ""
     }
   ]
 }

test/fixture/example-caption.output.json

@@ -55,9 +55,7 @@
     ],
     "examples": [
       {
-        "title": "example",
         "description": "foo(1);",
-        "lineNumber": 3,
         "caption": "demonstrates how to run foo"
       }
     ],

test/fixture/multiexample.output.json

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

test/fixture/params.output.json

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

test/fixture/simple-two.output.json

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