jsdoc / jsdoc/jsdoc

Issue with Markdown plugin, since 3.6+

Open
#1,668 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

Hi, I'm the author of the plugin jsdoc-vuejs and I've just faced a rendering issue with JSDoc 3.6+.

To give you some context, the plugin parse JSDoc to find props/data/methods/... from Vue components, it generates HTML code and inject it into a doclet's description to provide a nice page like this:

Capture d’écran de 2019-07-31 22-34-49

But since the last minor realease, it does not fully work anymore. Some code is interpreted as a markdown block and is escaped into <pre><code>...</pre></code> (as you will see below).

Input code

Code from Counter component:

<template>
  <div>
    {{ counter }}
  </div>
</template>

<script>
/**
 * @vue-data {Number} [counter=0] Counter value
 */
export default {
  name: 'Counter',
  data() {
    return {
      counter: 0,
    };
  },
  mounted() {
    this.interval = setInterval(() => this.increment(), 1000);
  },
  beforeDestroy() {
    clearInterval(this.interval);
  },
  methods: {
    /**
     * Increment the internal counter.
     */
    increment() {
      this.counter += 1;
    }
  }
};
</script>

JSDoc configuration
module.exports = {
  plugins: [
    '../', // will load jsdoc-vuejs plugin
    'plugins/markdown',
  ],
  source: {
    include: [
      'src/',
      'src/better-components',
      'src/js',
      'README.md',
    ],
    includePattern: '\\.(vue|js)$',
  },
  opts: {
    encoding: 'utf8',
  },
};

JSDoc debug output
DEBUG: JSDoc 3.6.0 (Sat, 04 May 2019 22:43:05 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":["../","plugins/markdown"],"recurseDepth":10,"source":{"includePattern":"\\.(vue|js)$","excludePattern":"","include":["src/","src/better-components","src/js","README.md"]},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false},"opts":{"encoding":"utf8"}},"opts":{"_":[],"destination":"docs","configure":".jsdoc.js","debug":true,"encoding":"utf8"}}}
DEBUG: Parsing source files: ["/home/kocal/Dev/jsdoc-vuejs/example/src/Counter.vue","/home/kocal/Dev/jsdoc-vuejs/example/src/better-components/BetterCounter.vue","/home/kocal/Dev/jsdoc-vuejs/example/src/js/CounterJS.js","/home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent.js","/home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent2.js"]
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/Counter.vue ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/better-components/BetterCounter.vue ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/CounterJS.js ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent.js ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent2.js ...
DEBUG: Finished parsing source files.
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 0.31 seconds.
Done in 0.42s.

Expected behavior

rendered:
Capture d’écran de 2019-07-31 22-21-01

source code:
Capture d’écran de 2019-07-31 22-20-17

Note how is rendered the <tr> in <tbody>. It looks like a valid markdown block code and so it's parsed and rendered like a block of code (see below).

Current behavior

rendered:
Capture d’écran de 2019-07-31 22-21-10

source code:
Capture d’écran de 2019-07-31 22-20-51

A block of code has been parsed and rendered.

Workaround

I've just found a workaround while writing this issue (but I still plan to open it for informational purpose 😄 ). If I remove extra blank lines like this:

Capture d’écran de 2019-07-31 22-42-41

then it works for both JSDoc <3.6 and >=3.6.

Your environment
Software Version
JSDoc 3.6.0 and more
Node.js 12.7.0
yarn 1.17.3
Operating system Debian Stretch

Thanks :)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the plugins/markdown configuration and reproduce the issue using the supplied Counter.vue example and JSDoc configuration. Compare rendering with JSDoc 3.6.0 and earlier versions, focusing on the extra blank lines that cause the HTML table content to become a code block. Done means the table renders as HTML without removing those blank lines, while the documented workaround remains unnecessary.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.