TUTORIAL: How to customize colors and subdue the bright colors in the doxygen comments

[ElectricRCAircraftGuy]

1. How to customize colors in VSCode by using the built-in "Scope inspector" tool

This isn't a question--it's a tutorial to help myself and others. If you enable the wiki I'll put it there.

Or, I can open a PR to put it in the readme if you like. Let me know if you'd like me to open a PR and I can put this info into the readme.

How to customize colors and subdue bright colors in C and C++ doxygen comments.

With the default settings in the Monokai ST3 theme, this code:

/// @brief      A brief one or two line description of the function.
/// @param[in]  variable_1  Input parameter
/// @param[in]  variable_2  Another input parameter
/// @param[out] variable_3  Output parameter
/// @param[out] variable_4  Another output parameter
/// @return     None
void myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here
}

/// \brief      A brief one or two line description of the function.
/// \param[in]  variable_1  Input parameter
/// \param[in]  variable_2  Another input parameter
/// \param[out] variable_3  Output parameter
/// \param[out] variable_4  Another output parameter
/// \return     None
void myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here
}

/** \brief      A brief one or two line description of the function.
 *  \param[in]  variable_1  Input parameter
 *  \param[in]  variable_2  Another input parameter
 *  \param[out] variable_3  Output parameter
 *  \param[out] variable_4  Another output parameter
 *  \return     None
 */
void myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here
}

...looks like this:

Notice how bright and vivid the param markers and variable names are in the doxygen comments! I hate it. I want those colors subdued so they don't distract me. I like the comments to be subdued, like Sublime Text does it by default. Here is what it looks like in Sublime Text 4 with Monokai, from Sublime Text 3, selected:

See how ALL of the comments are the same? Anyway, I don't mind the param and variable names being different, but they must be subdued. Here's how to customize their colors:

Open the settings.json file by doing Ctrl + Shift + P, and typing "Preferences: Open Settings (JSON)". This opens the ~/.config/Code/User/settings.json file.

Copy and paste the below "workbench.colorTheme" and "editor.tokenColorCustomizations" key-value entries into it, so it looks something like this:

{
    "workbench.colorTheme": "Monokai ST3",
    "editor.tokenColorCustomizations": {
        "[Monokai ST3]": {
            "textMateRules": [
                {
                    "name": "Doxygen variable names",
                    // This works! YOU **MUST** put the wider scope FIRST, and then the narrower scope after!
                    "scope": [
                        "comment.block.documentation.cpp variable.parameter.cpp",
                        "comment.line.double-slash.documentation.cpp variable.parameter.cpp",
                    ],
                    "settings": {
                        "foreground": "#a6a292",
                    },
                },
                {
                    "name": "Doxygen keywords, such as 'param' and 'brief'",
                    "scope": "storage.type.class.doxygen.cpp",
                    "settings": {
                        "foreground": "#7C8E9C",
                    }
                },
            ]
        }
    },
}

Note that the "name" fields are arbitrary and you can write whatever you want in them. The "scope" and "settings" fields inside the "textMateRules" are the important ones!

Save the file. Here is what the above code looks like now. The comments are much more subdued now, distracting less from the code:

If you want to make the param doxygen keywords and variable names the same as the rest of the comments, like it is in Sublime Text, just set the "foreground" color codes above to "#75715E" instead, which is the color of all the rest of the comments.

How to inspect colors and tokens so you can do your own customizations (use "Developer: Inspect Editor Tokens and Scopes" tool)

Do Ctrl + Shift + P and type "Developer: Inspect Editor Tokens and Scopes". Run that command. Click around the code now to see what color and scope something is. Example: here you can see that I have clicked on the @param doxygen keyword. The below information box shows up. You can see that the "textmate scopes" are:

storage.type.class.doxygen.cpp                // most-narrow scope
comment.line.double-slash.documentation.cpp
source.cpp                                    // broadest scope

These are in order of hierarchy. The most-narrow scope is at the top, and the broadest scope is at the bottom.

So, to specify this scope, we can use one or more scope names from above, with the broader scope listed first and the narrower scopes listed after, and in that order.

For this example above, the scope would be "comment.line.double-slash.documentation.cpp storage.type.class.doxygen.cpp", if I chose to use 2 levels of scope to describe this word.

As you can see in my settings above, for the "Doxygen variable names" I specified 2 levels of scope for both scopes I wanted to set to that color, so that I could be specific enough that it would properly exclude scopes I did NOT want to force to that color.

References

1. Scope Inspector: https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#scope-inspector

[ElectricRCAircraftGuy]

See also: How do I change color of comments in visual studio code?

[ElectricRCAircraftGuy]

For Python block comment strings, see my new answer on Stack Overflow here:

2. How to subdue Python block comment strings in VSCode in order to look like Sublime Text's Monokai