5

TL;DR: Where does the JS comment-appending behavior of the VSCode "Editor Hover" box come from and can it be adapted to use // comments?

When editing .js/.ts files, VSCode shows a box when the mouse hovers over any reference to a variable (controlled with the Editor > Hover settings).

/** I'm a comment */
const someVariable = 'Me';

console.log(someVariable);

results in the following when hovering over someVariable in the last line:

Screenshot of a variable showing a comment in the hover.

The comment portion of that box only appears if it is a multi-line comment beginning with two asterisks, one or more lines above a variable, object property, or function, in line with Intellisense's use of JSDoc. Very useful, but some team members prefer to put // comments at the end of a short line where a variable was declared. Is there any way to make VSCode take these end-of-line comments into account for variables/properties, or would I have to convert every relevant comment to /** to see it like this?

Improve this question
4
  • 1
    It seems that its standard to use block comments /** */ for documentation. See jsdoc.app/about-getting-started.html Commented Aug 12, 2020 at 6:32
  • Why would you do that ? I don't think this is possible. '//' is already used for comment a line, use it for another purpose may cause trouble. Better keep the standard Commented Aug 12, 2020 at 6:34
  • 1
    @VLAZ Variables are merely easiest to demo; the most valuable use is keys on objects and TypeScript interfaces, frequently imported into other files. Most of those manage without comments, but there's always a few keys whose minimal distinct description is like "Latest line-to-neutral voltage for conductor 2 in tenths of a volt", or state machine enumerations that need to describe exactly what situation/behavior of an external device a particular number corresponds to. Commented Aug 12, 2020 at 9:02
  • 1
    I've created an issue on VSCode here. Please upvote it to show your support. github.com/microsoft/vscode/issues/215550 Commented Jun 14, 2024 at 16:22

3 Answers 3

Reset to default
3

This 2 minute video was pretty helpful for me to see the advantages of using the jsDoc format. Instead of Ctrl K Ctrl C in vscode I'm going to start typing /** which autocompletes the comments similar to visual studio code typing /// in c# to autogenerate the comments template, etc. Here's the video: Quickly writing JSDoc comments in JavaScript and TypeScript

Improve this answer
Sign up to request clarification or add additional context in comments.

2 Comments

Agreed, it is not hard - the question is mostly a workaround to a coding culture.
I know it doesn't seem like much, but having to type /** really adds up, especially if you use comments for variables. To avoid wrist/tendon strain from the **, I'd recommend my code snippet. Unfortunately I couldn't figure out how to toggle off a JSDoc comment like you can with regular comments with ctrl+/ .
1

Unfortunately VSCode doesn't seem to support showing regular // comments in the popup. I've created an issue on VSCode here to request this feature. Please upvote it to show your support. https://github.com/microsoft/vscode/issues/215550

In the meantime, here's a VSCode keybinding I use to conveniently add a JSDoc-style comment:

{
  {
    "key": "shift+cmd+/",
    "command": "editor.action.insertSnippet",
    "when": "editorTextFocus",
    "args": {
      "snippet": "/** ${TM_SELECTED_TEXT/\\s*\\/\\/\\s*//}$1 */"
    }
  },
}

I also use prettier-plugin-jsdoc to auto-wrap multi-line comments.

Why would you do that ? I don't think this is possible. '//' is already used for comment a line, use it for another purpose may cause trouble. Better keep the standard.

This is nonsense. Regular comments are used for documenting and explaining code. JSDoc is just a more well-defined commenting format to include richer details. They both serve the same purpose.

Yes, regular comments are also sometimes used to temporarily remove code from execution, and that might not be something you prefer to show in the popup. But I'd gladly once in a while see a commented-out line of code in the popup if it meant I could always see documentation/descriptions too. Nothing else useful is taking up that space anyway.

Regardless of that, your opinions on the distinction between comment styles, or anything else, IDEs should at least have an option to have regular comments show in the popup.

Improve this answer

Comments

-1

JS/TS has these different comment syntaxes because they serve different purposes:

  • // and /* */ — Commenting on code (or commenting out code)

  • /** */ — Documenting symbols

You may not like the /** */ syntax, but this is a widely understood convention in JS/TS that is understood across many different editors and tools. Better to adopt to follow these conventions than fight the language ecosystem to make this work

Improve this answer

2 Comments

Your distinction is not as widely accepted as you think it is. Tons of dev comment symbols with regular comments, especially newbies or those coming from other languages. If the VSCode team doesn't have the resources to dedicate to making an optional setting for this or thinks the solution should be in userland to reduce settings complexity, that's understandable! But how about saying that instead of "you just don't understand my puristic distinction between the two".
Also I find your attitude in the issue and this answer condescending. "You may not like the syntax". Nowhere did anyone say that. I listed very real and understandable ergonomics issues like the quick toggling, and instead of trying to be helpful -- e.g. "maybe there's an extension to soothe your pain points" -- you immediately dismiss it and treat it as "user lack of knowledge".

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.