doxygen を使用してプロジェクトのドキュメントやコメントを管理する-PHPチュートリアル-php.cn

[オリジナル] doxygen を使用してプロジェクトのドキュメントまたはコメントを管理する

1. Doxygen アプリケーションシナリオ:

doxygen を使用して現在の主流のプログラミングを管理できます言語の注釈は文書システムを形成します。 (C、C、C#、Objective-C、IDL、Java、VHDL、PHP、Python、Tcl、Fortran などが含まれます)。 Doxygen 公式 Web サイトのアドレス (http://www.doxygen.nl/) 最近、API インターフェイスのメンテナンスにほとんどの時間が費やされています。より重要な側面の 1 つは、作成したインターフェイスによって呼び出し元がどのように理解できるかということです。一目でわかる使用法。それは社内の無線サーバーとクライアントの連携であっても、外部に公開されたAPIインターフェースであっても同様です。インターフェイスドキュメントを管理するために doxygen と svn フックを組み合わせて数日試してみたところ、これは非常に便利で実用的でした。 doxygen の公式 Web サイト自体は実際に doxygen を使用しています。より具体的な効果を確認したい場合は、http://www.doxygen.nl/ を直接参照してください。

以下に私が作成したレンダリングの一部を掲載します。実際に使用するときは、会社の UI 部門に美化を依頼してください。あまり行ったことはありません。UI エクスペリエンスを考慮してください:

2. インストール: Doxygen は現在、Windows、Mac OX、Linux などの主流システムを完全にサポートしています。そしてそれは基本的に、現在主流のすべてのプログラミング言語で使用されています。ここでは、ubuntu システムでのソースコードのコンパイルとインストールのプロセスを簡単に紹介します。その他のインストール方法は公式サイトをご覧ください。

```
gunzip doxygen-$VERSION.src.tar.gz tar xf doxygen-$VERSION.src.tar
```
ログイン後にコピー
環境チェック doxygen をインストールするには、ubuntu でのいくつかの依存関係のサポートが必要です。 ./configure シェルスクリプトがある解凍されたディレクトリを入力します。コマンド sh ./configure を実行して、インストール環境を確認します。現在のシステムが満たしている依存関係と、不足している依存関係がいくつかリストされます。 ubuntu では、sudo apt-get install xxxx (依存関係名) を使用するだけで、不足している依存関係をすべて 1 つずつインストールできます。このステップも非常に高速です。
補足
: make と make install について。私は個人的に、make の直後にソースパッケージ内で xxx/bin/doxygen コマンドを使用して、インストールせずにドキュメントを生成することを好みます。なぜなら、後で実際に文書を生成するためにこれを使用するとき、デフォルトのものの多くを変更する必要があることがわかるからです (もちろん、変更しなくても全く問題ありません。使用できないわけではありません) 。このとき、先ほど解凍したソースコードパッケージ内のxxx/src/配下にあるソースコードファイルを見つけて、対応する機能モジュールを実行する.cppファイル（cで書かれたソースコード）を直接変更することができます。 c ファイルを自分で作成し、make で再コンパイルします。このようにして、doxygen を任意の効果に変更できます。簡単な例を挙げると、デフォルトでは、doxygen はコードをチェックして関数を呼び出します。 API インターフェースでは、関数を関数ではなくインターフェースと呼ぶことを好みます。他の変更も同様です。

3. doxygen を使用した設定ファイルの設定:

ここでは、doxygen は複数の形式でドキュメントを提供します。主に HTML を使用するため、この HTML 上で Web サービスを設定し、Web 上でドキュメントを使用できます。doxygen には 200 以上の設定項目があり、これらは設定ファイルを通じて完了できます。、一般的に使用される構成手順をいくつか示します:

コマンド xxx/doxygen -g を使用すると、現在のディレクトリにデフォルト設定ファイル doxygen.conf が生成されます。デフォルトの設定ファイルを開くと、その中の各設定項目が設定名と設定値というキーと値の形式になっていることがわかります。ある程度の英語の知識がある場合、基本的に設定は簡単ではありません。問題。
詳細な構成手順については、http://www.stack.nl/~dimitri/doxygen/manual/ を参照してください。 config.html
ABBREVIATE_BRIEF //Alias
ALLEXTERNALS //すべての外部ドキュメント
ALPHABETICAL_INDEX //アルファベット順インデックス
ALWAYS_DETAILED_ SEC //詳細説明部分
binary_toc // バイナリ演算
Brief_member_desc // メンバーの短い説明
call_graph // 🎜>
DOTFILE リスト表示
ENABLE_PREPROCESSING //「前処理」を許可するdirectives
ENUM_VALUES_PER_LINE //各行の列挙値
ENABLED_SECTIONS //パスの例
Example_patterns // ファイル形式 (*.cpp、*.h、*.java など)
// アルファベット順のインデックスを列形式で表示
COMPACT_LATEX //圧縮された LATEX ドキュメント
COMPACT_RTF //圧縮された RTF ドキュメント
CREATE_SUBDIRS //「サブディレクトリ」を作成します
DETAILS_AT_TOP //ドキュメントの詳細 Head
DIRECTORY_GRAPH //INDEX を無効にする

DOT_MULTI_TARGETS

EXCLUDE_PATTERNS
EXPAND_AS_DEFINED //事前定義された拡張子
EXTERNAL_GROUPS //外部プラグインパッケージに使用
EXTRACT_ALL //すべてのローカルクラスを抽出
Extract_local_Methods // すべてのローカルメソッドを抽出します
Extract_private // すべてのプライベートメソッドを抽出します
EXTRACT_STATIC //ファイルパスFILTER_PATTERNS //制御形式 (メインバージョン:第 1 バージョン:第 2 バージョン番号)
FILTER_SOURCE_FILES / / バージョン元のファイルの制御
FULL_PATH_NAMES 🎜 > //自動定義ファイル形式を生成
GENERATE_BUGLIST //バグリストを生成
GENERATE_CHI //「ギリシャ文字」を生成
Generate_DepRciantEdlist // 「評価」リストを生成します
Generate_html // HTML を生成
GENATE_HTMLHELP / / htmlhelp を生成
GENERATE_LEGEND
GENERATE_PERLMOD
GENERATE_RTF
GENERATE_TAGFILE
GENERATE_TESTLIST
Generate_todolist // todolist を生成
Generate_treeview // 🎜>
GENERATE_XML // XML を生成
GRAPHICAL_HIERARCHY 🎜>GROUP_GRAPHS //グループグラフ
HAVE_DOT
HHC_LOCATION //場所を非表示
HIDE_FRIEND_COMPOUNDS //「複合」友達タイプを非表示
HIDE_IN_BODY_DOCS //ドキュメントの本文を非表示にします
HIDE_SCOPE_NAMES //「スコープ」名を非表示
HIDE_UNDOC_CLASSES //「アーカイブされていない」クラスをすべて非表示
HIDE_UNDOC_MEMBERS //「未アーカイブ」のメンバーをすべて非表示にする
HIDE_UNDOC_RELATIONS //「未アーカイブ」を非表示にする関係
HTML_ALIGN_MEMBERS //HTML ドキュメント内のメンバーの配置
HTML_FOOTER //HTML フッター設定
html_header
>Ingrore_prefixraph> // includepicture
include_path //継承文書の相続関係
inline_info /「相続」
INLINE_SOURCES 🎜>INPUT 書式設定 (重要)
INTERNAL_DOCS // 内部文書 >
LATEX_BATCHMODE //LATE X コマンド名
LATEX_HEADER 🎜>
LATEX_OUTPUT >
// MAN 拡張機能 🎜> MAN_LINKS //MAN リンク設定 >
MAX_DOT_GRA PH_DEPTH //DOT マップの最大深度
MAX_DOT_GRAPH_HEIGHT //DOT マップの最大の高さ
MAX_DOT_GRAPH_WIDTH //DOT グラフの最大幅
MAX_INITIALIZER_LINES //最大初期化行
MULTILINE_CPP_IS_BRIEF //複数の CPP ファイルの簡単な説明
MULTILINE_CPP_IS_BRIEF //複数の CPP ファイルの簡単な説明
OPTIMIZE_OUTPUT_FOR_C //最適化設定for C
OPTIMIZE_OUTPUT_JAVA //JAVA 設定の最適化
OUTPUT_DIRECTORY //出力パス設定 (重要)
OUTPUT_LANGUAGE //出力言語設定 (重要)
PAPER_TYPE //PDF 形式のハイパーリンク設定 (重要)
PERL_PATH //perlmod LATEX
PERLMOD_PRETTY // perlmod LATEX 🎜 > // perlmod MAKE ファイルのバージョン PREFIX
事前定義
project_nameCompositionメンバー（重要）
//相互参照 (重要)
//相互参照関係 repeat_brief
RTF_EXTENSIOLE
RTF_HYPERLINKS
RTF_STYLESHEET_FILE
show_directories // ディレクトリを表示します
Show_inClude_files // 含まれているファイルを表示します (一般的に NO、それ以外の場合は大きすぎます)
show_used_files // 使用されているファイルを表示します (一般的にはい)
SKIP_FUNCTION_MACROS // のマクロをスキップします関数（重要）、初心者はジャンプしないのが最善です//ドキュメントの短い要約
STRIP_CODE_COMMENTS //コメントを形成するバーコードを除外します (重要)
Strip_from_inc_path // どのヘッドファイルが含まれるかを除外します (重要)
STRIP_FROM_PATH // 除外されるバーコードパス
サブグループ //TAB シンボルサイズ設定 (重要)
TAGFILES / / テンプレートの関係設定 (重要)
TOC_EXPAND // 樹形図で表示される幅の設定（重要）
uml_look // UML の外観設定 (重要)
USE_WINDOWS_ENCODING // Windows システムのエンコード形式を使用する (重要) )
VERBATIM_HEADERS >
WARN_FORMAT //警告フォーマット指定(重要)
WARN_IF_DOC_ERROR //ドキュメントにエラーが発生した場合に警告を表示する
warn_no_paramdoc// //パラメーター文書警告形式の設定なし//警告設定（重要）
🎜> XML_SCHEMA // XML モード設定 (重要)

四、doxygen配置完成后注释的书写

当你配置好doxygen后，今后你基本上的时间都是花在你代码当中的注释的书写和维护。想要利用doxygen来管理文档。那么代码的注释就必需严格要求。

下面是我所用到的常用注释的书写要求，其他的更多请参考：http://www.stack.nl/~dimitri/doxygen/manual/commands.html

/** * @brief 这里用brief来说明接口方法的主要功能 * @date   接口方法的创建时间 * @author 接口方法的创建人 * @param  : 参数说明如下表： * name     | type     |description of param  * ----------|-----------|-------------------- * car_id   | int      |车源编号 * province | int      |业务员所在省份 * x        |  x       |   x * x        |  x       |   x * x        |  x       |   x * @return    返回值说明如下： * name     | type     | description of value * -------- |----------|---------------------- * car_id   | int      | 车源编号 * car_info | object   | json对象格式的车源信息 * @warning   该接口需要告知给调用者看的一些警告 * @attention 该接口需要告知给调用者看的一些注意事项 * @note      该接口的一些备注说明。通常用于当后者对该接口有较大改动的时候。备注一下某个时间点某人改动了什么东西 * @ todo     该接口的一些未完成的待办内容 */public function newSale() {    do someting; }

ログイン後にコピー

按照规范书写注释后，在页面文档中展示的效果如下：

在项目内部可以提前约定好书写规则，余下的只要大家按照这个规则来维护即可。当然人毕竟是人，不可能保证所有的代码都能按照预期的注释规则书写。因此doxygen的配置文件里面可以指定日志文件的路径。你可以好好利用这个日子文件，用相应的脚本语言写一小段代码来分析这个日志文件，然后人性化点展示到web页面上面。指定的管理人员定期的去查看下注释错误日志，即可即时纠正不对的注释内容。

五、doxygen的比较常用的特性

markdown语法的使用，doxygen完美的支持所有markdown语法。你可以在注释中使用任何markdown语法。也可以直接在项目doxygen配置文件中指定的INPUT路径下面书写md文件。你可以把如何使用文档？如何书写注释？等等一些公告内容用md文件来存放。这样，每个md文件就会再html文档系统里面独立生成一个页面。并在左侧形成一个独立的菜单。
别名的使用。利用配置文件里面的ALIASES可以设置注释别名，在书写注释的过程中，经常有些东西是必须写，而又一成不变的东西可以使用别名来简化。详见：http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html
由于每次修改完代码后，都需要用doxygen命令来重新生成文档，文档才会更新。所以如果你的文档对实时性的要求比较高的话，可以考虑借助公司内部的版本管理系统的hook来实现。我使用的是svn hook里面的post-commit来实现，当程序员把自己书写的代码提交svn的时候，hook去自动重新执行doxygen命令来更新文档。这样就能做到文档的实时更新，而不需要我们码农去做什么。
生成后的文档系统的左侧菜单往往并非我们想要的结果。我们希望改为一些我们自己的连接或者我们自己的显示名称。这事可以利用配置文件里面的LAYOUT_FILE = DoxygenLayout.xml （名称可以自己定，这是默认名称）。执行命令 doxygen -l 会在当前目录下面生成当前文档的默认layout文件DoxygenLayout.xml，打开编辑DoxygenLayout.xml里面的xml内容就可以改变左侧的菜单接口。具体自己研究了哈，这里不细说。
header.html 和 footer.html 页头和页尾的自定义。是否感觉生成的文档的界面并不那么的尽如人意，尝试自己写个页头和页尾。只是简单的html，首先你要获取到系统默认的header.html和footer.html，然后在默认的基础上面修改。获取默认header.html和footer.html和页面css的命令为：doxygen -w html new_header.html new_footer.html new_stylesheet.css YourConfigFile。
修改页面的样式，使其拥有更好的UI体验。可以使用配置文件中的 HTML_STYLESHEET 或者 HTML_EXTRA_STYLESHEET 来写自己的样式css文件或者扩展css文件。只需要在配置文件里面把两个配置指向你自己的css文件路径即可。
制作一个你自己的Logo图片，再把系统上面的按个默认的doxygen的logo给替换下就万事大吉了。替换logo使用配置项：PROJECT_LOGO 。