15

私のライブラリには、次の形式の関数オーバーロードがたくさんあります。

/// \brief Does thing.
///
/// \details The thing that is done is very special.
template<typename T>
void do_stuff(const T& t);

/// \brief Does thing repeatedly. 
/// \copydetails do_stuff()
template<typename T>
void do_stuff(const T& t, std::size_t x);

これは、一般的に機能し、非常に優れていますが、同じドキュメントセクションを複数回作成します。私が望むのは、これらの機能をグループ化することです。詳細な説明と、簡単な説明で注釈が付けられた各オーバーロードがあります。また、このようなことを行うエイリアスや入力フィルターも嫌いではありません。

これが想像できる1つの方法は次のとおりです。

ドキュメントの結果は次のようになります。

template<typename T>
void do_stuff(const T& t);                (1)

template<typename T>
void do_stuff(const T& t, std::size_t x); (2)

The things that is done is very special.

(1) Does thing.

(2) Does thing repeatedly.

もちろん、新しいページを作成してその種のドキュメントを手動で書くことはできますが、そのページで関数宣言を繰り返してから、実際の関数ドキュメントへのリンクを打ち込む必要がありますが、それは他の何よりもハックです。

これを簡単に達成する方法はありますか？それを dox​​ygen にハックするヒントさえあれば幸いです。

4

2 に答える 2

15

残念ながら、Doxygen にはこれを行うメカニズムがありません。取得できる最も近いものはメンバー グループですが、それらは必要なことを行いません (メンバー プロトタイプのリストにのみ表示されます)。

Doxygen 自体を変更せずに Doxygen にハッキングすると、通常、XML 形式の解析が必要になり、多くの問題が発生します。まず、その XML 形式は、何をするにも役に立たない (信じてください。試してみました) 。次に、これらの関数間のリンクを作成するための構文がありません。copydetails行は#includeC/C++ に似ています。インクルージョン後に痕跡を残しません。そのため、実際にいつ使用されたかはわかりません。

第三に、Doxygen が提供する他のすべてのフォーマットを破棄することになります。興味のある形式の完全なジェネレーターを作成することになります。

これをサポートするために Doxygen 自体を変更するには、いくつかの手順が必要です。まず、コマンドをリンクする特別な文法を追加する必要があります。これには、グループ化されているFuncDef別のクラスへの参照を持つようにクラスを変更することが含まれFuncDefます。次に、HTML ジェネレーターを変更して、同じ場所に生成する必要があります。それは思ったよりもずっと難しいでしょう。Doxygen の内部ソース コードが、私が最後に見たときよりも大幅に改善されていない限り、それを行うのはかなりの苦痛になるでしょう。

HTML ジェネレーターには、どのリンクが何にリンクしているかについて、いくつかの基本的な仮定があり、探しているものがそれらを壊します。そして覚えておいてください: あなたは Doxygen からこれを欲しがった最初の人ではありません. それでも、それはまだ行われていません。その理由の 1 つは、実装が簡単ではないことです。正直なところ、別の理由は、Dimitri が、これが実際に文書化されるべきものであると信じていないことだと思います。

于 2012-08-14T12:58:20.343 に答える
12

You can use @name tag to reach the similar functionality. Take a look at the example, that's easy.

    /**
     * @name Appends data to the container.
     *
     * @param tag Name of the data entry
     * @param value Data value
     */
    //@{
    /**
     * @brief Documentation for this overload
     */
    void append(const std::string & tag, bool value);

    /**
     * @brief Documentation for this overload
     */
    void append(const std::string & tag, int8_t value);

    void append(const std::string & tag, int16_t value);
    void append(const std::string & tag, int32_t value);
    //@}

It produces the following output:enter image description here

I hope this will help

于 2012-08-20T09:13:18.280 に答える