microsoft / microsoft/vscode-cpptools

Documentation comments don't show mathematical formulas in IntelliSense

Open
#9,000 3 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug Feature: Doc comments Language Service Visual Studio
Dominant language
TypeScript
Stars
6.2k
Forks
1.7k
Avg merge
14h 46m
Merged PRs (30d)
61

Description

Bug type: Language Service

As seen in the attached image, VS-Code doesn't display mathematical formulas in C++ documentation comments.
image

Note that I've inserted some new lines between the doc comments and the function so that you can see them clearly, however this does not affect the issue. It persists when there are no extra new-lines added.

This has been mentioned in this issue, however was marked closed after being determined to somehow be a duplicate of this (seemingly) un-related issue, which was marked as fixed in an older release (1.8.2).

I have tried using various formats to no avail (see the mathematical formula sections of this and this):

  • Different types of block comments:
    • ///
    • /** */
  • Different formula tags (with and without spaces around the formula):
    • @f[formula@f]
    • \f[formula\f]
    • \f{formula\f}
    • \f$formula\f$
  • Inclusion and exclusion of other tags such as @brief, <summary> etc

Additional info:

  • OS: Windows 11 Home x64 - Version 21H2 - Build 22000.493
  • VS Code Version: 1.65.1
  • C/C++ Extension Version: v1.8.4
  • Issue persists when cpptools is the only extension installed

c_cpp_properties.json configuration:

{
    "configurations": [
        {
            "name": "Win32",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/source"
            ],
            "defines": [
                "_DEBUG",
                "UNICODE",
                "_UNICODE",
            ],
            "windowsSdkVersion": "10.0.19041.0",
            "compilerPath": "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Tools\\MSVC\\14.30.30705\\bin\\Hostx64\\x64\\cl.exe",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "windows-msvc-x64",
            "forcedInclude": [
            ]
        }
    ],
    "version": 4
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the IntelliSense rendering of C++ documentation comments and reproduce the issue in VS Code using the supplied c_cpp_properties.json and formula formats. Review linked issues 6136 and 6084 for prior investigation; done means supported mathematical formulas display in the documentation popup. No source file or test is named in the report.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, typescript, vscode
Domain
developer-experience, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.