問題タブ [doxygen]

私は C++ スタティック ライブラリを作成しており、実装ファイルに doxygen コメントを付けています。私はドキュメンテーションについてあまり気にする必要はありませんでしたが、現在、ユーザーのために適切にドキュメンテーションする必要があることに取り組んでいます。また、コーディングだけを行い、ドキュメンテーションを行いたくないという以前の悪い習慣を、より優れたソフトウェア エンジニアリングに置き換えようとしています。慣行。

とにかく、先日、ライブラリのユーザー向けのタイプ (doxygen マニュアル) と、実装の詳細を扱う将来のメンテナー向けのコメントの 2 つの異なるタイプのドキュメントが必要であることに気付きました。

私の解決策の 1 つは、ファイル、クラス、およびメソッドの doxygen コメントを実装ファイルの最後に置くことです。そこでは邪魔にならず、メソッド定義の中や周りに通常のコメントを含めて、プログラマーに利益をもたらすことができます。手間がかかることは承知していますが、2 つの別々のタイプのコメント/ドキュメントを実現するための最良の方法のように思えます。同意しますか、または役立つ可能性のある解決策/原則がありますか. サイトを見回しましたが、これを扱ったスレッドを実際に見つけることができませんでした。

また、インターフェイス ファイルにコメントを散らかしたくはありません。インターフェイス自体に語らせたほうがよいと思うからです。ユーザーがライブラリ インターフェイスをより深く理解する必要がある場合に、マニュアルを参照できるようにしたいと考えています。私はここで正しい軌道に乗っていますか？

ご意見やご感想をお待ちしております。

編集：コメントをありがとうございます。私はそれらを聞いて多くのことを学びました。メンテナーにとって役立つコード コメントからユーザー マニュアルを分離する方法について、理解が深まったと思います。ライブラリの使用方法を説明するのに役立つ「散文」スタイルのマニュアルを作成するという @jalf のアイデアが気に入っています。これは単なるリファレンスマニュアルよりも優れていると本当に思います。とは言っても……リファレンスマニュアルもかなり重宝しそうな気がします。彼のアドバイスを他の人の考えと組み合わせて、ハイブリッドを作成しようと思います.コードにマニュアル全体が差し込まれていないという考えでした。これを回避するには、doxygen のすべてのコメントを実装ファイルの末尾に配置します。これにより、ヘッダーがきれいになり、実装がきれいになり、実装を維持している人にとって有用なコメントが配置されます。これが実際に機能するかどうかを確認します。これらは、これまでに学んだことに対する私の考えです。私のアプローチがうまくいくか、実用的であるかについては確信が持てません。時間だけが教えてくれます。

Eclipse 3.5 で eclox を動作させるにはどうすればよいですか?

Ubuntu 9.04 を使用しています。ubuntuリポジトリ（バージョン1.5.8）からDoxygenをインストールしました。次に、更新サイトからeclipseにecloxをインストールしました。

それにもかかわらず、それを開始するためのオプションがどのメニューにもありません。

また、eclox サイトには「入門」ガイドがないようです。

助けてください。

PHP プロジェクトでは、メイン アプリケーションにフロント コントローラー ロジックが使用されている場合でも、多くのスタンドアロン スクリプトや ajax スニペットなどが存在する可能性があります。

スクリプトの最初のコメント ブロックで、スクリプトが受け入れる/要求する GET および/または POST パラメーターと、それらがどのタイプであるかを定義する標準化された方法 (PHPDoc またはその他) はありますか?

私は通常@param、ファイルが関数であるかのように s を追加@returnし、スクリプトの動作と戻り値の説明を追加するだけで自分自身を助けますが、私が知らないより専門的な方法があるかもしれません。

doxygen のラテックス出力に関して 2 つの質問があります: 関連するページ (\page によって作成されたページ) を整理するにはどうすればよいですか? (ページのタイトルに従って整理されているようです) どの latex スタイルシートを使用するかを指定するには? (Doxyfile には何も見つかりませんでした)

クラスメンバーの段落番号を削除したいと思います。

ありがとう

私は C プロジェクトに取り組んでおり、さまざまな作成者とさまざまなドキュメンテーション スタイルを見てきました。

私はdoxygenやその他のドキュメント生成ツールの大ファンで、このプロジェクトを移行してこれらのシステムの 1 つを使用したいと考えています。

ソースコードのコメントをスキャンして、「説明」、「作成者」、「ファイル名」などのキーワードやその他の種類のコンテキストをスキャンして、コメントを標準形式にインテリジェントに変換できるツールを知っている人はいますか? そうでない場合は、クレイジーなスクリプトを作成するか、手動で変換できると思います。

ありがとう

クライアントがヘッダーファイルを表示できるようにするために設定SOURCE_BROWSER = NOしました。VERBATIM_HEADERS = YESただし、特定のヘッダーのみを表示できるようにしたいのです。これを行うための最良の方法はどのようになりますか。

助けてくれてありがとう！

編集：これは機能しているように見えますが、他のより良い方法に興味があります。

誰かが文書化されていないxslファイルからコード構造を抽出できるツールを知っていますか？

xslファイルからドキュメント要素を抽出してhtmlリファレンスページを作成できるXSLTdocがあることは知っています。しかし、文書化されていないxslファイルの場合、XSLTdocの出力はかなり役に立ちません。

コードが文書化されていなくても、Doxygenは貴重な出力を生成できます。xslに匹敵するツールはありますか？

私がこれまでに見つけた最高のものはdepgraphです。この小さなスタイルシートは、インクルードとインポートの依存関係グラフを生成します。

私が探しているのは、xslテンプレート用のコールグラフジェネレーターです。

コメントブロックのバージョンを変更する方法はありますか？

例えば

私は前処理でこれを行う方法を知っています、そして私は他の方法があるかどうか疑問に思いましたか？

関連するメモとして、ドキュメントやアプリケーションなどのバージョン番号の変更を、あちこちで異なるバージョン番号を変更せずにどのように処理しますか？現在VER、すべての人がアクセスできる名前空間に-like変数があります（基本的に、名前空間の汚染なしにグローバルです）。

名前空間とモジュールを認識する Doxygen に問題があります。\addtogroupを名前空間内に配置するか、名前空間外に配置するかが問題だと思います。

例 1、名前空間の外:

例 2 - 名前空間内

namespace RecordsをDoxygen Namespacesタブの下に表示し、間接的にModulesタブの下に表示したいと思います。Namespacesページのアイテムをクリックすると、を含むページが生成されますRecords::Interface。[モジュール] タブのアイテムをクリックすると、を含むページも生成されますRecords::Interface。

私の Doxygen のドキュメントでは、このジレンマに起因する不一致のために、 モジュールにある名前空間タブに欠落している項目があり、その逆も同様です。

では、例 1 と例 2 のどちらが適切な方法でしょうか。{Doxygen マニュアルは、このトピックについて明確ではありません。}
Doxygen: \addtogroup
Doxygen: 名前空間の文書化