Lint code in documentation code blocks

[sindresorhus]

I often include code examples in my documentation comments and it would be useful if TypeScript ESLint could lint that code too. I always try to make sure that the code examples are fully runnable by themselves, so would be nice to be able to ensure that's true with linting.

For example:

/**
 * @example
 * ```
 * import foo from 'foo';
 * 
 * foo(bar: string);
 * //=> '✨'
 * ```
 */
function foo() {}

[bradzacher]

My only issue with this is that typescript doesn't run on the code in comments, which means it's easy to provide us with code that is syntactically valid, but not semantically valid, and potentially break assumptions that rules make.

Note that typescript-estree purposely doesn't throw if the semantics of the code are bad during its parse because it's not intended to be a replacement for tsc

[sindresorhus]

@bradzacher True, but it's still better than nothing.

[mysticatea]

Named processors may fit this request: eslint/eslint#11552
For example, it defines the named processor that extracts @example code.

[bradzacher]

Just like how we don't parse code in markdown files - I don't think parsing code in JSDoc comments is within the purview of this project.

This is something that is better suited to a pre-processor - similar to how markdown code fences can be pre-processed for linting by eslint-plugin-markdown.