Skip to content

Markdown comment support for tooltip display of hover #6020

Closed
Closed
Markdown comment support for tooltip display of hover#6020
Labels
Feature: Doc commentsAn issue related to code comments shown in hover, completion, and signature help.Language ServicebugfixedCheck the Milestone for the release in which the fix is or will be available.quick fix
Milestone
1.17.0

Description

@DeadRabbits307
DeadRabbits307
opened on Aug 25, 2020

Type: LanguageService

Like the support for doxygen documentation (#658) the support for Markdown would be nice. Like in Rust:

2020-08-25-091128_1278x674_scrot

2020-08-25-093703_1278x1380_scrot

Activity

  1. Sean McManus (sean-mcmanus)
    added
    Feature Request
    Language Service
    on Aug 25, 2020

  2. sean-mcmanus commented on Aug 25, 2020

    @sean-mcmanus
    Sean McManus (sean-mcmanus)
    on Aug 25, 2020
    Contributor

    VS Code inherently supports markdown in doc comments, but we added code to explicitly disable/escape it for code that has comments that are not intended to be interpreted as markdown. We'd need to add a setting to re-enable the markdown.

  3. Sean McManus (sean-mcmanus)
    added
    Feature: Doc commentsAn issue related to code comments shown in hover, completion, and signature help.
    on Aug 25, 2020
  4. Bob Brown (bobbrow)
    added this to the Backlog milestone on Aug 27, 2020

  5. Leedehai commented on Oct 4, 2020

    @Leedehai
    Leedehai
    on Oct 4, 2020

    Following Sean McManus (@sean-mcmanus)'s response above.. Where can we re-enable that in code? I was trying to tweak files in ~/.vscode/extensions/ms-vscode.cpptools-1.0.1 so I can render the comment in Markdown without having to wait for a new Cpptools release :) It looks we just need to delete the code that is used to "explicitly disable/escape" Markdown.

  6. sean-mcmanus commented on Oct 5, 2020

    @sean-mcmanus
    Sean McManus (sean-mcmanus)
    on Oct 5, 2020
    Contributor

    The markdown escaping is done in our closed source cpptools process. I haven't looked into whether there's a way to undo the escaping via the open source TypeScript.

  7. ericdrobinson commented on Jun 8, 2021

    @ericdrobinson
    Eric Robinson (ericdrobinson)
    on Jun 8, 2021

    We'd need to add a setting to re-enable the markdown.

    I was surprised that there isn't a way to get markdown formatting already. We use this feature in other languages to great effect. Would very much love to see it enabled in C/C++.

  8. bshoshany commented on Jul 26, 2022

    @bshoshany
    Barak Shoshany (bshoshany)
    on Jul 26, 2022

    Hi Sean McManus (@sean-mcmanus), I came here to request this exact same feature and found that it was already requested. It's been almost 2 years since this issue opened and more than a year since the last reply, I wonder if any progress has been made into enabling Markdown comments in C/C++? This would be extremely helpful in writing more meaningful and informative code documentation for my C++ libraries. Thanks!

  9. sean-mcmanus commented on Jul 26, 2022

    @sean-mcmanus
    Sean McManus (sean-mcmanus)
    on Jul 26, 2022
    Contributor

    Barak Shoshany (@bshoshany) There hasn't been any progress yet. If you see this issue get assigned to a milestone then you could expect progress.

  10. bshoshany commented on Jul 26, 2022

    @bshoshany
    Barak Shoshany (bshoshany)
    on Jul 26, 2022

    Sean McManus (@sean-mcmanus), thank you so much for your quick reply. I understand that this is not a high-priority issue. However, from your post above, if I understand correctly, it sounds like allowing Markdown comments is a simple matter of re-enabling something that was disabled. If that is indeed the case, I wonder if perhaps you could consider putting this issue at a higher priority, since it is a low-effort fix?

  11. sean-mcmanus commented on Jul 26, 2022

    @sean-mcmanus
    Sean McManus (sean-mcmanus)
    on Jul 26, 2022
    Contributor

    It looks like it would be a medium effort fix. There's problems with how to combine the cpp formatted comments with the markdown comments and how to deal with potential security issues with exposing links in the comments.

  12. bshoshany commented on Jul 27, 2022

    @bshoshany
    Barak Shoshany (bshoshany)
    on Jul 27, 2022

    I see, thanks for explaining. I hope it gets implemented soon, as it would be a very helpful feature.

  13. pauljurczak commented on Jul 27, 2022

    @pauljurczak
    Paul Jurczak (pauljurczak)
    on Jul 27, 2022

    how to deal with potential security issues with exposing links in the comments.

    Ignore the links. Display them as a text.

  14. TomasVaner commented on Jul 27, 2022

    @TomasVaner
    Tomas Vaner (TomasVaner)
    on Jul 27, 2022

    Waiting for this feature actually. Because if comments would support markdown, the issue with multiline comments becoming one line text in the tooltip would be resolved.
    And I need multiline text in my documentation ;)

  15. 15 remaining items

  16. browntarik
    self-assigned this
    on Apr 11, 2023

  17. starball5 commented on Apr 28, 2023

    @starball5
    starball (starball5)
    on Apr 28, 2023

    Related on Stack Overflow: Using C/C++ in VS Code, how can I create lists and tables within tooltip description of symbols?.

  18. joule19 commented on May 23, 2023

    @joule19
    joule19
    on May 23, 2023

    Found out that my issue of using HTML tags within doxygen-styled comments for C++ can be related to the issue discussed here. Any chance to have soon markdown support (including HTML) for tooltip display of hover? :-)

    image

  19. sean-mcmanus commented on May 23, 2023

    @sean-mcmanus
    Sean McManus (sean-mcmanus)
    on May 23, 2023
    Contributor

    joule19 No, HTML would not be supported. Markdown is supported because that is what VS Code will process/render, i.e. I think VS Code itself would need to add support for that.

  20. browntarik
    added
    fixedCheck the Milestone for the release in which the fix is or will be available.
    on Jul 18, 2023

  21. michelleangela commented on Jul 27, 2023

    @michelleangela
    Michelle Matias (michelleangela)
    on Jul 27, 2023
    Contributor

    Fix available in pre-release https://github.com/microsoft/vscode-cpptools/releases/tag/v1.17.0.

  22. naksyl commented on Jul 29, 2023

    @naksyl
    Sylwester Nakonieczny (naksyl)
    on Jul 29, 2023

    There is still space to improve. It looks like in section every new line is removed, every line trimmed and joind with space. Not usable:

    • lists
    • code blocks
    /// ACTUAL - every section is paragraph                         | IDEAL - every section is markdown document
/// @brief This is a markdown test for doxygen hover            | @brief This is a markdown test for doxygen hover
///                                                             |
/// @details                                                    | @details
/// No way to to simple start new paragraph - only by duplicate | Simple way to to start new paragraph - by empty line
/// doxygen section                                             | doxygen section
///                                                             |
/// This paragraph is joined                                    | This paragraph is not joined
/// @details                                                    |
/// New paragraph                                               | New paragraph
/// @details                                                    |
/// Another paragraph                                           | Another paragraph
/// @details                                                    |
/// __Bold__ _italic_ `inline code` - works as expected         | __Bold__ _italic_ `inline code` - works as expected
///                                                             |
/// @details                                                    | Code block should be rendered render as actual block code
/// Code block is rendered render as inline code                |
/// even on it's own section                                    |
/// @details                                                    | ```c
/// ```c                                                        | puts("Hello World");
/// puts("Hello World");                                        | system("pause");
/// system("pause");                                            | ```
/// ```                                                         |
/// @note                                                       | @note                                               
/// Test markdown lists - again whole section is treated        | Test markdown lists - whole section is markdown document
/// as single paragraph                                         | as single paragraph                                 
/// @note                                                       |
/// - item1                                                     | - item1                                             
///    - subitem                                                |    - subitem                                        
/// - item 2                                                    | - item 2                                            
int variable;

    Zrzut ekranu 2023-07-29 092724

  23. thekpaul commented on Jul 29, 2023

    @thekpaul
    Paul Kim (김형준) (thekpaul)
    on Jul 29, 2023

    Sylwester Nakonieczny (@naksyl) For the new line problem, there's a separate issue at #10039 with a VS "feature request" ticket for it open here. Apparently it's a "design choice" to show line breaks as spaces instead of actual new lines, regardless of how many new lines we use in between.

    Code blocks also don't seem to be fully supported, but IIRC, if there's no explicit DOxygen tags inside the comment, the code block shows up in the same format as the actual body of the editor. This seems to be a similar behaviour to the new line problem, where, if we don't use DOxygen tags, the newlines are displayed as actual new lines instead of spaces.

    My personal hunch is that, without DOxygen tags, the comments are rendered as regular comments with line breaks and code block formatting, but as soon as a DOxygen tag is introduced, those functionality are suppressed.

    UPDATE: Got a screenshot of code blocks working if there aren't any DOxygen tags!
    image
    I suppose the astericks and underscore are shown with a preceding backslash as an escape sequence. If I add the backslash in the comment itself, the hover breaks at that character and doesn't show anything afterwards.

  24. naksyl commented on Aug 5, 2023

    @naksyl
    Sylwester Nakonieczny (naksyl)
    on Aug 5, 2023

    Ok, I misunderstood this markdown feature. It works for plain comments (no doxygen tags) - even tables.

    mea culpa

  25. Sean McManus (sean-mcmanus)
    modified the milestones: On Deck, 1.17.0 on Aug 8, 2023

  26. michelleangela commented on Aug 14, 2023

    @michelleangela
    Michelle Matias (michelleangela)
    on Aug 14, 2023
    Contributor

    Fixed in release version https://github.com/microsoft/vscode-cpptools/releases/tag/v1.17.2.

  27. Michelle Matias (michelleangela)
    closed this as completedon Aug 14, 2023
  28. Michelle Matias (michelleangela)
    unassigned
    browntarik
    on Aug 14, 2023
  29. github-actions
    locked and limited conversation to collaborators on Sep 29, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Feature: Doc commentsAn issue related to code comments shown in hover, completion, and signature help.Language ServicebugfixedCheck the Milestone for the release in which the fix is or will be available.quick fix

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions