microsoft / microsoft/vscode-cpptools

Doxygen alias support

オープン
#12,752 コメント 2 件 リアクション 3 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

Feature Request Feature: Doc comments Language Service
主要言語
TypeScript
スター
6.2k
フォーク
1.7k
平均マージ
14時間 46分
マージ済み PR(30日)
61

説明

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

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

このリクエストでは実装ファイルやテストが特定されていません。まず、リンク先の Doxygen エイリアスのドキュメントと提供された C の例を確認し、エイリアス、カスタムタグ、ホバー表示名が必要かどうかを明確にしてから、@input や @output などのタグが意図したとおりに解析されることを確認してください。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
typescript
領域
documentation
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
活発
明瞭さ
説明が足りない
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。