2021.04.18C/C++のドキュメント作成でdoxygenを使ってみたまとめです。向けのドキュメンテーションシステムです。PHP、C#、Dにもある程度対応しています。http://www.doxygen.jp/と、公式サイトで説明されている通り、ドキュメント生成を行うためのシステムです。※ライセンスはGPLで、無料で使うことができます。Macで使うことができます。下図はドキュメント生成のざっくりとした流れです。doxygenスタイルのコメントの記述方法からまとめていきたいと思います。基本doxygenはすべてのコメントをドキュメント化するのではなく、特定の形式で記述されたコメントのみをドキュメント化します。※全部ドキュメント化されると逆に困りますよね...doxygen形式のコメントの基本形がこれです。その3これらの形式で記述されたコメントのみがドキュメント化の対象となります。注意点は、コメント開始の/**やコメント終了の*/と、コメント文との間は半角スペースが必須なところです。複数行のコメントの場合は、以下のように記述します。コメント二行目*/※その2、その3も複数行で書けますがここでは省略します。複数行の場合も、コメントの本文と*との間には半角スペースが必須です。*/を以降使用していきます。doxygenコメントにはもう一つ覚えることがあります。それが、@detailのような特殊コマンドです。詳細説明ここに書かれたコメントは出力するドキュメントの詳細説明の欄に出力されます。細かい意味は以降の章で触れますので、ここでは、コマンドの前後は半角スペースが必須である点だけ抑えておいてください。ファイルのコメントこの章から、具体的なdoxygenスタイルコメントの説明をしていきます。ファイルに対するコメントです。ファイルに対するコメントがないと、グローバルな空間(名前空間の外)に定義した関数や変数の出力がなされなくなってしまいます。ドキュメント化対象のファイルには必ずファイルコメントをつけましょう。以下はサンプルになります。補足説明とかメモ*/@fileでファイル名、@briefでファイルの概要、@authorで作者名、@dateで作成日を記述できます。@dateは省略可能です。(構成管理しているなら不要なはず。コミット毎にこれを更新するのはクソダサい。)@detailは関数の詳細説明です。@noteは補足説明やメモです。@noteは、ファイル以外でも、関数や変数など、どのコメントでも使用可能です。以降の章での説明は省略していますが、使用可能なので必要に応じて使ってください。関数のコメント続いて関数のコメントです。注意点等はないので早速サンプルです。{...}@paramは引数の説明です。[in]は入力の引数、[out]は出力の引数(変更した値を呼び出し元でも使用する引数)です。引数が存在する場合のみ記載します。@returnは戻り値の説明です。戻り値が存在する場合のみ記載します(voidの場合は記載しません)。enum変数・定数のdoxygenコメントの書き方は共通です。〜*/形式でコメントを書けば自動的に変数・定数に対するdoxygenコメントとして扱われます。続いて、構造体・enumのコメントです。この二つの書き方も共通です。〜*/形式でコメントを書けば自動的に構造体・enumに対するdoxygenコメントとして扱われます。各メンバ・要素に対するコメントは省略しても問題ありません。クラスのコメント次は、クラスのコメントの書き方です。クラスそのものに対するコメントのサンプルです。{public:...private:...};クラスに対するコメントも、クラスの宣言の真上に記載すると、自動的にクラスのコメントとして扱われます。次に、コンストラクタ・デストラクタに対するコメントです。{};コンストラクタ・デストラクタに対するコメントは関数に対するコメントに近いです。コンストラクタ・デストラクタの真上に記載することで自動的にコンストラクタ・デストラクタとして扱われます。次に、メンバ関数・メンバ変数です。str_;メンバ関数は通常の関数と、メンバ変数は通常の変数と同じ記述方法で書くことができます。privateと言ったスコープは自動的に判定されるのでdoxygenコメント記載時は気にする必要はないです。名前空間のコメントnamespaceの上にdoxygenスタイルのコメントを記載すると自動的に名前空間のドキュメントとして扱われます。{}ファイルのコメントと異なり、名前空間のコメントは記載しなくても特に問題は起こりません。ダウンロード公式ページからバイナリをダウンロードします。Binariesという項目があり、その項にダウンロード用のソースとバイナリが用意されています。Mac(dmg形式)、Windows(exe形式)、Linux(バイナリのtarball)が用意されていたので、通常はコンパイル等は不要なはずです。10.15.4)で試したのでmacOS向けのバイナリをダウンロードしました。インストールダウンロードしたdmgファイルを開くと以下のような画面になります。Doxygen.appをアプリケーションにドラッグして追加します。追加したアプリケーションを開こうとすると、以下のエラーが表示されて開けないかと思います。"Doxygen.app"は、開発元を検証できないため開けません。その場合は、アイコンを右クリックし、[開く]を選択します。すると、以下の画面が表示されるので、もう一度[開く]を選択します。自己責任ですがこれで、以下のようなdoxygenのGUIのトップ画面が開くはずです。doxygenのインストールはこれで完了です。次回以降は普通にクリックして開くことができます。4.ドキュメント出力方法(HTML形式)次は実際にドキュメントを出力していきます。説明は、doxygenのウィザードに沿って進めていきます。プロジェクト設定doxygenを立ち上げると以下の画面になると思うので、まずは、プロジェクトの設定を行います。★の項目は必須項目なので全て入力してください。「★doxygenの作業ディレクトリ」にはソースコードのルートディレクトリを指定します。場合は「★生成対象のコードのディレクトリ」と同じになるかと思います。「★ドキュメント出力先ディレクトリ」に設定するパスは権限さえあればどこでも良いです。指定したディレクトリの下に”html”や”tex”のディレクトリが作成されます。必要箇所を入力したら[next]をクリックします。次にモードの設定を行います。基本的にはデフォルトでOKかと思いますが、一応触れておきます。Entities“を選択すると、ドキュメントを作成していないファイル・関数等についても自動的にドキュメントが出力されます。output“を有効化すると、参照されているコードのリンクが貼られるようになります。programming〜“は言語の選択です。今回はC++なのでデフォルトのままでOKです。[next]をクリック。出力の設定(HTML)次は出力の設定を行います。※ここの設定は見た目だけ問題ですので、趣味の範囲でどうぞ。今回はHTML形式のドキュメントを出力したいのでHTMLにチェックを入れます。panel“が個人的には見易かったです。color...でドキュメントの色を変更できます。デフォルトは綺麗な青色です。こんな禍々しくないです。ドキュメントの出力形式を決めたら[next]を選択します。最後にダイアグラムの設定を行います。packageの三択です。diagramsはグラフを出力しません。generatorはplant-umlの図を出力してるっぽいです。関連するクラスが2つ以上ないと図は出力されません。included”となっていたのですが、私の環境では動作しませんでした。グラフを出力するかどうかが決まれば、[next]をクリックします。doxygen]をクリックするとドキュメント出力が実行されます。出力されたHTMLは以下の感じになります。トップページクラス図HTML出力は以上になります。コメントをヘッダに記載するか否かC++の場合、宣言箇所と定義箇所が分かれて、どちらにdoxygen形式のコメントを記載するべきか迷うかもしれません。doxygenの動作としては、両方に記載した場合は、両方の内容が出力されてしまいます。特別な理由がない場合はどちらかに記載するべきです。doxygenの動作上、どちらに書いても動作するので、悩みどころではありますが、個人的には.cxxではなく.hxxのファイルに書くべきだと思います。基本的にドキュメントを後から見るのはコードを知らない人間(もしくは未来の自分)になると思います。コードを知らない時はヘッダファイルから読んでいくことが多いと思うんですよね。後からの見やすさとして、ヘッダーに書いておくべきではないかと思います。Codeで関数にカーソルを合わせた際に説明が表示されるのが地味に気に入っています。人に見せる可能性のあるソースコードには関数・クラスにコメントつけて欲しいところ。privateなメンバでも出力したい!doxygenではデフォルトだとprivateなメンバはドキュメント化されません。privateなメンバもドキュメント化したい露出狂な方におかれましては、以下を有効化してください。EXTRACT_PRIVATE、まさにと言ったネーミングですね。ところで、5章に突入してから気付いたんですが、この記事長すぎやしませんかね。自分でも確認のスクロールが面倒なんですよね。...なんと6187文字もあるみたいです。長文お付き合いいただきありがとうございました。タイーツマスクロ(mathkuro)をフォローするマスクロ(mathkuro)関連記事C/C++どうせならerrno書いてよ今日も表題の通りなんですけど、ログ仕込むならerrnoまで書いてよって話です。理想を言えばエラーが一切発生しないに越したことはないんですけど、まあ、現実問題としてそんなことはあり得ないじゃないですか?で、そんな時に皆さんログを埋め込ん...C/C++C/C++開発環境を整えるC++のコンパイラとboostをインストールする話。CentOS/Ubuntu/mac/Windows(オススメの紹介のみ)についてまとめています。socketのサンプルプログラムを作成しました。C/C++【C/C++】単体テストのすすめ(gtest)C/C++の単体テスト・自動試験のフレームワークの一つであるgtestについてまとめました。環境構築・サンプルコード・コンパイル方法を紹介しているので、この記事を読めばgtestが使えるようになります。gtestは導入が簡単で機能が豊富、さらにテストコードも書きやすいのでオススメです。C/C++C言語ソケット通信サンプルCでソケット通信のサンプルコードを書きました。サーバ・クライアント間で任意の長さのデータを送れるようにしておいたので結構汎用性があるかと思います。C/C++【Win11】3分でできる!C言語プログラミング環境構築インストール時に1GB弱のダウンロードが発生するので、ネットワーク等によっては3分以上かかる場合があります。令和の時代になっても、学校・会社を問わず、プログラミング入門でC言語をやるところは多いみたいですね。コメントをキャンセルメールアドレスが公開されることはありません。privateなメンバでも出力したい!参考このブログは、しがないプログラマーの戯言です。内容は私見であり、企業・団体を代表する内容ではありません。ブログ内容の実践に関しては自己責任となります。ブログ内容に誤りがありましたらお気軽にコメントをいただければ幸いです。CodeC/C++JavaScriptPythonお問い合わせホーム検索トップサイドバータイトルとURLをコピーしました。