RFC: Escaping doc comments inside doc comments

It’s useful to users to include code examples in documentation comments. Sometimes you need to illustrate what the output of different code examples are, so you put it in a comment below, and if it’s multiple lines, you use a block comment. The problem is that TSDoc doesn’t correctly parse this:

/**
 * ```
 * getAverage()
 * /* 'some output' */
 * ```
 */
function getAverage(x, y) {
    return (x + y) / 2.0;
}

I think it should handle block comments when they’re inside a code block in the documentation comment.

[jaydenseric]

I’ve been wrestling with this problem with JSDoc for years, both from the side as a user trying to document things, and as the creator of jsdoc-md which generates markdown API docs from JSDoc.

This seems like a lot of effort to work around a problem that could more readily be solved with “don’t put */ in your code examples”.

Here are a few common situations where you need to use */ in a JSDoc comment:

1. When documenting a glob string as a default parameter value, e.g:

   /** @param {string} [glob='**/*.js'] Glob pattern. */
   

   Real world examples:

   • https://github.com/jaydenseric/jsdoc-md/tree/v9.1.1#function-jsdocmd
   • https://github.com/jaydenseric/find-unused-exports/tree/v1.2.0#function-findunusedexports

2. When documenting a CLI command containing a glob, e.g:

   /**
    * @example <caption>CLI usage.</caption>
    * ```sh
    * npx jsdoc-md --source-glob **/*.{mjs,js}
    * ```
    */
   

   Real world examples:

   • https://github.com/jaydenseric/jsdoc-md/tree/v9.1.1#cli
   • https://github.com/jaydenseric/find-unused-exports/tree/v1.2.0#cli

3. When documenting template literal comment tags that have utility. A very common example is how linters, formatters, and syntax highlighters hook of the leading /* GraphQL */ comment to process the following template string containing GraphQL SDL. In the code examples of my server and client GraphQL related packages, I want any example containing a GraphQL query string to have /* GraphQL */ in front of them to get users in a good habit, and so that the GraphQL SDL within code example is Prettier formatted (via eslint-plugin-jsdoc and the jsdoc/check-examples rule).

   Example 1:

   /**
    * @example <caption>Setup for a schema built with [`makeExecutableSchema`](https://apollographql.com/docs/graphql-tools/generate-schema#makeExecutableSchema).</caption>
    * ```js
    * const { makeExecutableSchema } = require('graphql-tools');
    * const { GraphQLUpload } = require('graphql-upload');
    *
    * const schema = makeExecutableSchema({
    *   typeDefs: /* GraphQL */ `
    *     scalar Upload
    *   `,
    *   resolvers: {
    *     Upload: GraphQLUpload,
    *   },
    * });
    * ```
    */
   

   Another example of this situation is babel-plugin-syntax-highlight, which uses template string comment tags for build-time syntax highlighting. I had to give up on JSDoc for documenting that package, and manually write write code examples in the readme markdown:

   

   Real world examples:

   • https://github.com/jaydenseric/graphql-upload/blob/v11.0.0/public/GraphQLUpload.js#L35
   • https://github.com/jaydenseric/graphql-react/tree/v12.0.1#examples
   • https://github.com/jaydenseric/babel-plugin-syntax-highlight/tree/v2.1.0#usage

For jsdoc-md, I came up with the convention that */ within the content of JSDoc descriptions or types can be escaped with *\/, and before processing such content is run through an unescapeJsdoc function that simply replaces all occurrences of *\/ with */:

https://github.com/jaydenseric/jsdoc-md/blob/v9.1.1/private/unescapeJsdoc.js#L3-L24

Edit: Updated function: https://github.com/jaydenseric/jsdoc-md/blob/c37795fa1976e17aeb4acce1832795efefa093c9/unescapeJsdoc.mjs#L1-L22

There are problems with this convention though, unless the wider ecosystem adopts it. Firstly, VS Code displays the code example with the escape still there in intellisense tooltips:

Secondly, I haven’t figured out yet how to get the eslint-plugin-jsdoc rule jsdoc/check-examples to do the unescaping before attempting to parse examples as JS:

[octogonz]

This problem is fairly difficult. Users have a very strong expectation that a fenced code block is reproduced literally. For example, suppose we choose \ as our escape character. We get something like this:

/**
 * ```ts
 * /**
 *  * Matches "abc\/def" or "*\\/abc" but not "C:\\foo\\bar"
 *  *\/
 * function foo(path) {
 *   return /[a-z*]+\/[a-z]+$/.test(path);
 * }
 * ```
 */

If we allow \/ to be escaped by the /* */ framing, it needs to be just the / character. It would be wildly unacceptable to expand every single \ escape before TSDoc starts parsing the input, because \ is a standard escape character used by Markdown, JSDoc, and also source code.

But this means \/ gets expanded before \\. So the second layer of the onion skin will look like this:

```ts
/**
 * Matches "abc/def" or "*\/abc" but not "C:\\foo\\bar"
 */
function foo(path) {
  return /[a-z*]+/[a-z]+$/.test(path);
}
```

It’s highly confusing why the / in the RegExp got expanded but not the "C:\\, but I suppose someone could memorize that / is special. It’s particularly counterintuitive with "*\\/abc" where \\/ gets processed from right-to-left, whereas a casual reader would assume the opposite.

The */ might be more acceptable merely because people don’t use HTML escapes as much.