microsoft / microsoft/vscode-cpptools

Doxygen alias support

Open
#12,752 2 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Type: Feature Request

This is similar (if not identical) to https://github.com/microsoft/vscode-cpptools/issues/5700 - adding support for Doxygen aliases like @par instead of @param, @input instead of @param[in] etc.

My use-case is probably unique, working on a large codebase documented with SourceDoc [2], an older source documenting tool that uses a syntax which overlaps a lot with Doxygen and can be parsed by Doxygen specific tools (including cpptools) with the appropiate aliases.
However, generic Doxygen alias support is probably not that rare and might help others too.

Ideally, aliases would allow setting the display name in the hover, but for the regular Doxygen parsing those seem to be localized, so that part might be tricky.

If aliases are hard to implement, maybe we could at least define our custom tags and their hover diplay name.

Disabling Simplify Structured Comments is not a viable alternative, the result is too much of paragraph soup to be intelligible, we cannot customize the sections to be filtered in the hover etc.

Code example:

/**
 * @function cpptools_test1
 * @brief desc for this void func.
 *
 * @input   p1    Input arg.
 * @output  p2    Output args.
 */
static void
cpptools_test1(void *p1, void *p2)
{
   (void)p1;
   (void)p2;
}

[1] https://www.doxygen.nl/manual/config.html#cfg_aliases
[2] https://sourceforge.net/projects/scdoc/

Extension version: 1.22.3
VS Code version: Code - Insiders 1.94.0-insider (4f485cf59847506bc1ba2aaab127d31dcbe2c9dc, 2024-09-18T09:24:10.356Z)
OS version: Windows_NT x64 10.0.22631
Modes:
Remote OS version: Linux x64 4.18.0-513.11.1.el8_9.0.1.x86_64

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

The request does not identify implementation files or tests. Start by reviewing the linked Doxygen alias documentation and the supplied C example; clarify whether aliases, custom tags, and hover display names are required, then verify that tags such as @input and @output are parsed as intended.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.