microsoft / microsoft/vscode-cpptools

Incorrect Doxygen comments generated for certain C functions

Open
#11,282 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug Feature: Doc comments Language Service
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, enum or pointer to a forward-declared union.
  • Additionally, when a C function is of the form return_type func(void), an extra @param entry is generated.

Steps to reproduce:

  1. 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);
    
  2. Type /// above each function (or just use the context menu) to generate Doxygen comments.
  3. 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.