microsoft / microsoft/vscode-cpptools

Doxygen alias support

Offen
#12,752 2 Kommentare 3 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

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

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

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

Die Anfrage nennt keine Implementierungsdateien oder Tests. Beginnen Sie mit der Durchsicht der verlinkten Doxygen-Alias-Dokumentation und des bereitgestellten C-Beispiels; klären Sie, ob Aliase, benutzerdefinierte Tags und Hover-Anzeigenamen erforderlich sind, und überprüfen Sie anschließend, dass Tags wie @input und @output wie vorgesehen geparst werden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
typescript
Bereich
documentation
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Aktiv
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

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