Better error messages when jsdoc-parsing causes errors

- Errors during jsdoc-parsing where hardy recognizable as such
- This change makes it clear that they have occured in with jsdoc2md

Related to markedjs/marked#907. It took some time to determine the cause of
an error, because the error message and the stack-trace where not clear.

src/helpers.js

@@ -8,6 +8,16 @@ const jsdoc2md = require('jsdoc-to-markdown')
  */
 function jsdoc (globPattern) {
   return jsdoc2md.render({files: globPattern})
+    .catch((e) => {
+      if (e.name === 'JSDOC_ERROR') {
+        // Backward compatibility: Deprecated for 2.0
+        throw e
+      }
+      // Give a hint where other errors occur, but include the original error
+      const error = new Error(`Error while rendering jsdoc for "${globPattern}": ${e.message}`)
+      error.cause = e
+      throw error
+    })
 }
 
 module.exports = {

test/main-spec.js

@@ -12,6 +12,7 @@ chai.use(require('dirty-chai'))
 chai.use(require('chai-as-promised'))
 const expect = chai.expect
 const fs = require('fs')
+const jsdoc2md = require('jsdoc-to-markdown')
 
 const thought = require('customize')()
   .registerEngine('handlebars', require('customize-engine-handlebars'))
@@ -29,30 +30,54 @@ describe('thought-plugin-jsdoc:', function () {
     })
   })
 
-  it('the plugin though throw a meaningful error, if no file could be found by the glob', function () {
-    // ... because then the main-property of package.json is probably wrong
-    return expect(
-      thought
-        .merge(packageJsonMain('a-non-existing-file.js'))
-        .run()
-    ).to.be.rejectedWith(`These files do not exist: a-non-existing-file.js`)
+  describe('should throw a meaningful error', function () {
+    const render = jsdoc2md.render
+
+    afterEach(function () {
+      // Restore original render function (may be changed in tests to throw errors)
+      jsdoc2md.render = render
+    })
+
+    it('the plugin should throw a meaningful error, if no file could be found by the glob', function () {
+      // ... because then the main-property of package.json is probably wrong
+      return expect(
+        thought
+          .merge(packageJsonMain('a-non-existing-file.js'))
+          .run()
+      ).to.be.rejectedWith(`These files do not exist: a-non-existing-file.js`)
+    })
+
+    it('the plugin should mention that an error has occured during jsdoc creation', function () {
+      jsdoc2md.render = function (args) {
+        return Promise.reject(new Error('Some test-error'))
+      }
+      // The "javascript-file.js" does not exist and it does not have to, because in the line above, we have modified
+      // the render function to always throw an error
+      return expect(
+        thought
+          .merge(packageJsonMain('javascript-file.js'))
+          .run()
+      ).to.be.rejectedWith(`Error while rendering jsdoc for "javascript-file.js": Some test-error`)
+    })
   })
 
-  // Computed test-cases for different scenarios, see path below
-  const basePath = 'test/fixtures/scenarios'
-  fs.readdirSync(basePath).forEach(function (scenario) {
-    const scenarioDir = `${basePath}/${scenario}`
-    it('scenario ' + scenarioDir, function () {
-      // Run the engine
+  describe('test-scenario:', function () {
+    // Computed test-cases for different scenarios, see path below
+    const basePath = 'test/fixtures/scenarios'
+    fs.readdirSync(basePath).forEach(function (scenario) {
+      const scenarioDir = `${basePath}/${scenario}`
+      it(scenarioDir, function () {
+        // Run the engine
 
-      return thought
-        .merge(packageJsonMain(`${scenarioDir}/input*.js`))
-        .run()
-        .then(result => {
-          const expected = fs.readFileSync(`${scenarioDir}/expected.md`, {encoding: 'utf-8'})
-          fs.writeFileSync(`${scenarioDir}/actual.md`, result.handlebars['index.md'])
-          expect(result.handlebars['index.md']).to.equal(expected)
-        })
+        return thought
+          .merge(packageJsonMain(`${scenarioDir}/input*.js`))
+          .run()
+          .then(result => {
+            const expected = fs.readFileSync(`${scenarioDir}/expected.md`, {encoding: 'utf-8'})
+            fs.writeFileSync(`${scenarioDir}/actual.md`, result.handlebars['index.md'])
+            expect(result.handlebars['index.md']).to.equal(expected)
+          })
+      })
     })
   })
 })