microsoft / microsoft/vscode-cpptools

Incorrect Doxygen comments generated for certain C functions

Offen
#11,282 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

bug Feature: Doc comments Language Service
Vorherrschende Sprache
TypeScript
Sterne
6.2k
Forks
1.7k
Ø Merge
14 Std. 46 Min.
Gemergte PRs (30 T.)
61

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, das Problem in einer C-Datei anhand der Deklarationen und der im Bericht beschriebenen Schritte zur Doxygen-Generierung zu reproduzieren. Verfolge die Doxygen-Kommentargenerierung der C/C++-Erweiterung für Rückgabetypen, die struct, enum oder eine vorwärts deklarierte union enthalten, sowie für Funktionen mit void-Parametern. Als abgeschlossen gilt die Aufgabe, wenn die generierten Kommentare den Parameter für func(void) weglassen und die erwarteten @param- und @return-Einträge für die anderen Funktionen beibehalten.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
c, typescript, vscode
Bereich
tooling
Issue-Typ
Bug
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.