'@' in @example code block tries to render a custom tag
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 15.5k
- Forks
- 1.5k
- Avg merge
- 10d 23h
- Merged PRs (30d)
- 1
Description
When documenting code with an '@' symbol in the @example block, jsdoc thinks the '@' is a tag and breaks the rendering of the example code
Input code
/**
* Creates a LESS file with variable definitions based on the style dictionary
*
* @example
* ```
* @color-background-base: #f0f0f0;
* @color-background-alt: #eeeeee;
* ```
*/
function foo() {
}
JSDoc configuration
No configuration, also tried with the markdown plugin enabled, same thing happens.
JSDoc debug output
DEBUG: JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":[],"recurseDepth":10,"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":"(^|\\/|\\\\)_"},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false,"default":{"outputSourceFiles":true}}},"opts":{"_":["test.js"],"debug":true,"destination":"./out/","encoding":"utf8"}}}
DEBUG: Parsing source files: ["/Users/djb/Dev/jsdoctest/test.js"]
Parsing /Users/djb/Dev/jsdoctest/test.js ...
DEBUG: Finished parsing source files.
DEBUG: Indexing doclets...
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 0.23 seconds.
Expected behavior
Either provide a way to escape an '@' sign with a backslash, or have jsdoc ignore any content in triple ticks so that the '@' character does not trigger a tag.
Current behavior
jsdoc reads any '@' symbol as a tag even if it is within a code example.
Your environment
| Software | Version |
|---|---|
| JSDoc | 3.5.5 |
| Node.js | v9.6.0 |
| npm | 5.8.0 |
| Operating system | OSX 10.12.6 |
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the supplied JSDoc 3.5.5 example with the two LESS variables inside the @example block. Trace how JSDoc parses tags and fenced example content, then establish whether escaping @ or ignoring it inside triple backticks is the intended behavior and verify that the rendered example preserves both lines.
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
- Mostly clear
- Newbie friendliness
- 35/100