microsoft / microsoft/vscode-cpptools
Incorrect Doxygen comments generated for certain C functions
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 6.2k
- Forks
- 1.7k
- Avg merge
- 14h 46m
- Merged PRs (30d)
- 61
Description
Environment
- OS and Version:
Windows 11 22H2 (x64) - VS Code Version:
1.80.2 - C/C++ Extension Version:
1.16.3
Bug Summary and Steps to Reproduce
Bug Summary:
- Auto-generation of Doxygen comments for C functions breaks whenever the return type contains
struct,enumor pointer to a forward-declaredunion. - Additionally, when a C function is of the form
return_type func(void), an extra@paramentry is generated.
Steps to reproduce:
- Create a new C file with the following content:
struct Bar {}; union Bar2; enum Bar3 { BAR }; typedef struct Bar *BarType; int *foo(int bar); struct Bar foo_broken(int bar); union Bar2 *foo_broken2(int bar); enum Bar3 foo_broken3(int bar); unsigned long long int foo2(void); BarType foo3(int bar); int foo_broken_param(void); - Type
///above each function (or just use the context menu) to generate Doxygen comments. - Obtain incorrect/truncated Doxygen comments:
/// @brief /// @param bar /// @return int *foo(int bar); // correct (normal function) /// @brief struct Bar foo_broken(int bar); // truncated /// @brief union Bar2 *foo_broken2(int bar); // truncated /// @brief enum Bar3 foo_broken3(int bar); // truncated /// @brief /// @param bar /// @return unsigned long long int foo2(int bar); // correct, despite having multiple tokens in the return type /// @brief /// @param bar /// @return BarType foo3(int bar); // correct, because `struct` is not present /// @brief /// @param /// @return int foo_broken_param(void); // incorrect, an extra unnamed parameter is generated
Expected behavior:
Having
/// @brief
/// @return
generated for foo_broken_param (which doesn't take any parameters), and
/// @brief
/// @param
/// @return
generated for every other function.
Configuration and Logs
c_cpp_properties.json: (Default Settings)
Other Extensions
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the issue in a C file using the declarations and Doxygen-generation steps in the report. Trace the C/C++ extension's Doxygen comment generation for return types containing struct, enum, or forward-declared union, and for functions with void parameters. Done means generated comments omit the parameter for func(void) and preserve the expected @param and @return entries for the other functions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, typescript, vscode
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100