Custom Block Comment Formatting/Better Comment Formatting

[pzuraq]

We've been using doc comments more and more in our code to automatically generate documentation, which is starting to be really productive. Tools like ESDoc and Typedoc are capable of statically analyzing the code and producing a ton of helpful docs.

Our generator setup generally compiles the description in doc comments as Markdown, which makes writing examples super easy. Except, VSCode's comment blocks in Javascript interfere with this quite a lot, specifically the leading * characters on each line. There are two main ways it is problematic:

1. Copy pasting a snippet into a doc block comment does not add leading *, which results in having to add an asterisk to each line. This can be very painful with large examples:

/**
 * this is an example function, here's how you use it
 * 
 * ```js
//example.js
foo();
 */

2. Tabbing does not tab relative to the doc comment block, but the overall document. This means that tab depth is off by one when writing examples in doc blocks, which results in really wonky indentation:

/**
 * this is an example function, here's how you use it
 * 
 * ```js
 * //example.js
 * foo({
 *  bar: 'baz'
 * });
 */

One solution here is to allow a way to customize block comments. We are currently using comments without a preceding asterisk:

/**
  this is an example function, here's how you use it
  
  ```js
  //example.js
  foo();
*/

This is good for the most part, but VSCode doesn't expect it and actively fights it to some extent. It'll insert asterisks whenever we try to start a comment block, and if you copy paste some code after a block it'll mess up indentation (likely because it thinks that the closing */ represents the indentation level, but it's set back one space). The below example was a real world attempt to copy-paste the function and the comment:

    /**
      Helper function to click with options like the meta key and ctrl key set

      @param {Object} options - click event options
    */
   async clickWith(options) {
    await click(findElement(this), options);
  },

Another option would be to fix the comment blocks so the editor can handle them, allowing users to type markdown in line at proper indentation levels, and copy paste with preceding asterisks added. I think both options would be great wins for DX, especially since markdown helps with code examples in comments so much.

[vscodebot]

(Experimental duplicate detection)
Thanks for submitting this issue. Please also check if it is already covered by an existing one, like:

• Allow toggle line comment accurately when language only support nested block comment (#9311)

[paulxtiseo]

For JavaScript, the "Document This" extension does a good job of formatting the appropriate comment block.

However, it would be nice if VSCode could collapse those kinds of blocks natively.

[pzuraq]

I tried out the Document This extension, but it doesn't appear to address the issues I outlined above. It's still very difficult to embed markdown within a doc comment and have indentation work as expected, and indentation on copy/paste is still messed up when using doc comments without a leading asterisk before each line.

[rishacha]

Is there anyone working on this? Can I try and work on it? It seems like a problem I would like to fix because I face it everyday.

[rishacha]

Actually #20044 addresses this issue. I simply disabled all extensions for comments and it worked

[IanVS]

Regarding #50301 (comment), I tried running with extensions disabled, and vscode still does not add leading asterisks correctly. Document This also does not add leading asterisks when making a new line. I'm using VSCode 1.40, FWIW.

[rebornix]

This is due to the limited architecture (regex based indentation rules and only support limited code styles), we may want to consider using formatters if they exist for indenation adjustment (if interested, we can discuss in #19847).

For this particular issue, if the indentation rules are leading to more trouble than having no auto indent, you can set editor.autoIndent to advanced to disable the regex based indentation adjustment or use auto formatting (editor.formatOnType, editor.formatOnPaste). As we don't have an easy good-enough fix for it, we close it for now and explore better solutions through issues like (#19847 and #34621).