検索

ホームページ >バックエンド開発 >PHPチュートリアル >doxygen を使用してプロジェクトのドキュメントやコメントを管理する

doxygen を使用してプロジェクトのドキュメントやコメントを管理する

WBOY
WBOYオリジナル
2016-06-13 12:11:011301ブラウズ

[オリジナル] 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 システムでのソース コードのコンパイルとインストールのプロセスを簡単に紹介します。その他のインストール方法は公式サイトをご覧ください。

    ubuntu14.04 の doxygen ソース コードをダウンロードします。公式 Web サイトのダウンロード オプションには、Ubuntu に特に適したバージョンがあります。ダウンロードしたソースコードパッケージの命名形式はおおよそ次のとおりです: doxygen-{doxygen バージョン番号}.src.tar.gz 解凍します。コマンドは次のとおりです: 

  2. <span style="color: #0000ff;">gunzip</span> doxygen-$VERSION.src.<span style="color: #0000ff;">tar</span><span style="color: #000000;">.gz </span><span style="color: #0000ff;">tar</span> xf doxygen-$VERSION.src.<span style="color: #0000ff;">tar</span>
    環境チェック doxygen をインストールするには、ubuntu でのいくつかの依存関係のサポートが必要です。 ./configure シェル スクリプトがある解凍されたディレクトリを入力します。 コマンド sh ./configure を実行して、インストール環境を確認します。現在のシステムが満たしている依存関係と、不足している依存関係がいくつかリストされます。 ubuntu では、sudo apt-get install xxxx (依存関係名) を使用するだけで、不足している依存関係をすべて 1 つずつインストールできます。このステップも非常に高速です。

    4. 次のステップは sudo make と sudo make install です。 make または make install プロセス中に何かが足りないというプロンプトが表示される場合。 sudo apt-get install xxx でインストールできます。

    5. 終了したら、コマンド ラインの下でコマンド doxygen --version を実行してみてください。 バージョン番号が表示されれば、インストールは成功しています。

  6. 補足

    : make と make install について。私は個人的に、make の直後にソース パッケージ内で xxx/bin/doxygen コマンドを使用して、インストールせずにドキュメントを生成することを好みます。 なぜなら、後で実際に文書を生成するためにこれを使用するとき、デフォルトのものの多くを変更する必要があることがわかるからです (もちろん、変更しなくても全く問題ありません。使用できないわけではありません) 。 このとき、先ほど解凍したソースコードパッケージ内のxxx/src/配下にあるソースコードファイルを見つけて、対応する機能モジュールを実行する.cppファイル（cで書かれたソースコード）を直接変更することができます。 c ファイルを自分で作成し、make で再コンパイルします。 このようにして、doxygen を任意の効果に変更できます。簡単な例を挙げると、デフォルトでは、doxygen はコードをチェックして関数を呼び出します。 API インターフェースでは、関数を関数ではなくインターフェースと呼ぶことを好みます。 他の変更も同様です。

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

    doxygen の使用は次のようになります。正しいです。構成ファイルの構成は、構成ファイルをわずかに構成してからコマンド xxxx/doxygen xxxx.conf を実行するだけで必要なドキュメントを生成することを意味します (

    ここでは、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 // 🎜>
      • CASE_SENSE_NAMES // 検出された例の名前
      • CHM_FILE //CHM 形式ファイル
      • CLASS_DIAGRAMS //クラステーブル
      • CLASS_GRAPH // // DOT パス設定
      • DOT_TRANSPARENT
    • DOTFILE リスト表示
    • ENABLE_PREPROCESSING //「前処理」を許可するdirectives
    • ENUM_VALUES_PER_LINE //各行の列挙値
    • ENABLED_SECTIONS //パスの例
    • Example_patterns // ファイル形式 (*.cpp、*.h、*.java など)
      • COLS_IN_ALPHA_INDEX
    • // アルファベット順のインデックスを列形式で表示
    • 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 を生成
      • /LATEX を生成
    • GENERATE_LEGEND
      • //MAN ファイルを生成
    • GENERATE_PERLMOD
      • //Perl スクリプトを生成します
    • GENERATE_RTF
      • //RTF を生成
    • GENERATE_TAGFILE
      • //フラグファイルを生成
    • GENERATE_TESTLIST
      • //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
      • html_output
    • >Ingrore_prefixraph> // includepicture
    • include_path //継承文書の相続関係
    • inline_info /「相続」
    • INLINE_SOURCES 🎜>INPUT 書式設定 (重要)
    • INTERNAL_DOCS // 内部文書 >
    • LATEX_BATCHMODE //LATE X コマンド名
    • LATEX_HEADER 🎜>
    • LATEX_OUTPUT >
      • MAKEINDEX_CMD _NAME
    • // 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メンバー（重要）
      • REFERENCED_BY_RELATION
    • //相互参照 (重要)
      • REFERENCES_RELATION
    • //相互参照関係 repeat_brief
      • // 「短い説明」を再設定して状態を開きます
    • RTF_EXTENSIOLE
      • //// / RTF 展開ファイル
    • RTF_HYPERLINKS
      • //RTF 出力設定
    • 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来管理文档。那么代码的注释就必需严格要求。

    1. 下面是我所用到的常用注释的书写要求，其他的更多请参考：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的比较常用的特性

    1. markdown语法的使用，doxygen完美的支持所有markdown语法。你可以在注释中使用任何markdown语法。 也可以直接在项目doxygen配置文件中指定的INPUT路径下面书写md文件。你可以把如何使用文档？如何书写注释？等等一些公告内容用md文件来存放。这样，每个md文件就会再html文档系统里面独立生成一个页面。并在左侧形成一个独立的菜单。

    2. 别名的使用。利用配置文件里面的ALIASES可以设置注释别名，在书写注释的过程中，经常有些东西是必须写，而又一成不变的东西可以使用别名来简化。详见：http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html

    3. 由于每次修改完代码后，都需要用doxygen命令来重新生成文档，文档才会更新。所以如果你的文档对实时性的要求比较高的话，可以考虑借助公司内部的版本管理系统的hook来实现。我使用的是svn hook里面的post-commit来实现，当程序员把自己书写的代码提交svn的时候，hook去自动重新执行doxygen命令来更新文档。这样就能做到文档的实时更新，而不需要我们码农去做什么。

    4. 生成后的文档系统的左侧菜单往往并非我们想要的结果。我们希望改为一些我们自己的连接或者我们自己的显示名称。这事可以利用配置文件里面的LAYOUT_FILE = DoxygenLayout.xml （名称可以自己定，这是默认名称）。 执行命令 doxygen -l 会在当前目录下面生成当前文档的默认layout文件DoxygenLayout.xml，打开编辑DoxygenLayout.xml里面的xml内容就可以改变左侧的菜单接口。具体自己研究了哈，这里不细说。

    5. 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。

    6. 修改页面的样式，使其拥有更好的UI体验。可以使用配置文件中的 HTML_STYLESHEET 或者 HTML_EXTRA_STYLESHEET 来写自己的样式css文件或者扩展css文件。只需要在配置文件里面把两个配置指向你自己的css文件路径即可。

    7. 制作一个你自己的Logo图片，再把系统上面的按个默认的doxygen的logo给替换下就万事大吉了。替换logo使用配置项：PROJECT_LOGO 。

    doxygen的功能还远远不止我上面介绍的那些，还有很多丰富多彩的功能，有想要使用这东西的人，可以自己去doxygen官网上面学习下哈。本文可随意转载，但是请务必注明原文出处。

    1楼sunlovesea
    UI其实挺好看的，清新简洁

声明：
この記事の内容はネチズンが自主的に寄稿したものであり、著作権は原著者に帰属します。このサイトは、それに相当する法的責任を負いません。盗作または侵害の疑いのあるコンテンツを見つけた場合は、admin@php.cn までご連絡ください。
前の記事：このパーセント記号が何を意味するのか教えてください。次の記事：このパーセント記号が何を意味するのか教えてください。

関連記事

続きを見る