Merge pull request #330 from lavrton/empty-example-fail-fix

Fix throwing error when "example" tag is empty

Author: tmcw

lib/lint.js

@@ -34,6 +34,15 @@ 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);
@@ -51,6 +60,10 @@ function lintComments(comment) {
     if (tag.title === 'param' && tag.type) {
       checkCanonical(tag.type);
     }
+
+    if (tag.title === 'example') {
+      checkEmptyExample(tag);
+    }
   });
   return comment;
 }

lib/output/html.js

@@ -14,9 +14,9 @@ var walk = require('../walk'),
 function highlightString(auto) {
   return function (example) {
     if (auto) {
-      return hljs.highlightAuto(example).value;
+      return hljs.highlightAuto(example || '').value;
     }
-    return hljs.highlight('js', example).value;
+    return hljs.highlight('js', example || '').value;
   };
 }
 

test/fixture/empty-example.input.js

@@ -0,0 +1,8 @@
+/**
+ * This function returns the number plus two.
+ *
+ * @example
+ */
+function returnTwo() {
+  return a + 2;
+}

test/fixture/empty-example.output.json

@@ -0,0 +1,46 @@
+[
+  {
+    "description": "This function returns the number plus two.",
+    "tags": [
+      {
+        "title": "example",
+        "description": null,
+        "lineNumber": 3
+      }
+    ],
+    "loc": {
+      "start": {
+        "line": 1,
+        "column": 0
+      },
+      "end": {
+        "line": 5,
+        "column": 3
+      }
+    },
+    "context": {
+      "loc": {
+        "start": {
+          "line": 6,
+          "column": 0
+        },
+        "end": {
+          "line": 8,
+          "column": 1
+        }
+      },
+      "code": "/**\n * This function returns the number plus two.\n *\n * @example\n */\nfunction returnTwo() {\n  return a + 2;\n}\n"
+    },
+    "errors": [],
+    "examples": [null],
+    "name": "returnTwo",
+    "kind": "function",
+    "members": {
+      "instance": [],
+      "static": []
+    },
+    "path": [
+      "returnTwo"
+    ]
+  }
+]

test/fixture/empty-example.output.md

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

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

@@ -0,0 +1,59 @@
+{
+  "type": "root",
+  "children": [
+    {
+      "depth": 1,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "returnTwo"
+        }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "children": [
+        {
+          "type": "text",
+          "value": "This function returns the number plus two.",
+          "position": {
+            "start": {
+              "line": 1,
+              "column": 1
+            },
+            "end": {
+              "line": 1,
+              "column": 43
+            },
+            "indent": []
+          }
+        }
+      ],
+      "position": {
+        "start": {
+          "line": 1,
+          "column": 1
+        },
+        "end": {
+          "line": 1,
+          "column": 43
+        },
+        "indent": []
+      }
+    },
+    {
+      "type": "strong",
+      "children": [
+        {
+          "type": "text",
+          "value": "Examples"
+        }
+      ]
+    },
+    {                                           
+         "lang": "javascript",
+         "type": "code"
+    }
+  ]
+}