check-examples exampleCodeRegex option with global and multiline expression flags

[jaydenseric]

It would be great if the check-examples rule exampleCodeRegex option could work with global and multiline expression flags, so that multiple markdown code blocks could be linted per example. Here is a contrived example, supported by jsdoc-md:

/**
 * @example <caption>Say `Hello!` to the user.</caption>
 * First, import the function:
 * 
 * ```js
 * import popup from './popup'
 * ```
 *
 * Then use it like this:
 *
 * ```js
 * popup('Hello!')
 * ```
 *
 * Here is the result on macOS:
 *
 * ![Screenshot](path/to/screenshot.jpg)
 */

Here is an example /^```(?:js|javascript)\n([\s\S]*?)```$/gm pattern for the exampleCodeRegex option:

https://regexr.com/4h9sh

Each regex result should be linted in isolation; I tried quickly adding gm flags to the source code here:

eslint-plugin-jsdoc/src/rules/checkExamples.js

Line 70 in f0c246c

exampleCodeRegex = exampleCodeRegex && new RegExp(exampleCodeRegex, '');

But that caused weirdness where ESLint would not allow the same named const in two code blocks, etc. and the errors for following code blocks were reporting in the wrong places.

[jaydenseric]

🤔alternatively, perhaps there is a way to lint the whole example content as markdown, using something like this: https://github.com/eslint/eslint-plugin-markdown

[brettz9]

Regarding linting as Markdown...

With the approach of eslint in how (pre)processors work (which is what eslint-plugin-markdown uses), the processor (only one of which is apparently applicable at a given time), extracts usable JavaScript out of a given file type. It sounds to me like using this on JavaScript files would rule out using regular eslinting on those files (unless one were running it in a separate process with a different config). (If you liked that route, you'd probably need to file a request of eslint to support non-exclusive processors so that one run could be treated as JavaScript, and another as Markdown blocks within the JavaScript (which in turn had their own JavaScript blocks); you'd then need eslint-plugin-markdown to implement such a processor.)

There is one other possibility outside of our plug-in. You could define the equivalent of an eslint processor for https://github.com/remarkjs/remark (they only appear to support plugins themselves, though the project they are associated with at https://github.com/unifiedjs/unified support processors, albeit focused apparently more on text, rather than code) Such a processor would find the jsdoc blocks within JavaScript files and then find the Markdown within those blocks. The advantage of this approach is that you could get linting of your Markdown within the jsdoc blocks along the way, as well as the lint JavaScript example blocks within them. The disadvantage is that it would not be integrated with your regular coding error messages, but would instead be added with any Markdown styling rules you wanted to enforce.

But in any case, I think that it is not inconceivable to handle this in eslint-plugin-jsdoc' check-examples. I don't think there is any need to add or support a full-blown Markdown parser (such as jsdoc supports through its Markdown plugin which converts Markdown to HTML), as we are only interested in the JS blocks, and the comment-parser library we use is now more aware of these blocks (#395). (comment-parser would incidentally also be useful if taking the Remark preprocessor approach instead.)

[brettz9]

Btw, whoever might find time to work on this issue, might also knock out #211 (indent rule issues with check-examples) and possibly part of #336 (fixer for bad js within examples) at the same time. The trim and join settings for comment-parser are now documented, so that should hopefully help, as I figure we might not be using those properly for that rule's needs.

[gajus]

🎉 This issue has been resolved in version 18.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀