サンプルを見ながらDoxygenの理解を深める

Published: 2018年9月29日 by tomsato

概要

前にDoxygenの入門についてまとめたが実際にサンプルを見た方が理解が早いかと思うのでサンプルを作ってみる

Doxygen入門の入門

↑前に書いた記事、そっちでは

  • Doxygenについての簡単な説明
  • 導入方法
  • 書き方

などを書いた

今回は、まずサンプルを見て理解をしたい人向けに
サンプルのアプリケーションをGitHubに用意して、ドキュメントもGitHub Pagesで見られるようにしてみた

作成したサンプルについて

アプリケーション

サンプルのソースコード

↑こちらのGitHubのリポジトリに乗せた

サンプルのソースコードは以下のように実装している

  • PHPで実装
  • Slimフレームワークを使用
  • MVCを採用

サンプルのソースコードからページを表示するまでの流れ(MacOSでのやり方)

$ php -v
PHP 5.6.30

$ git clone git@github.com:tomsato/doxygen-slim.git
$ cd doxygen-slim/
// サブモジュールのファイル(Doxygen関連のファイル群)を持ってくる
$ git submodule update --init --recursive
$ composer install
$ composer start

この状態で「localhost:8080」を見ると「Home testtttt.」がページに表示されることがわかる

またこちらの記事でDoxygenコマンドをインストールしていた場合は

$ doxygen

を実行するとdocs/以下にDoxygenドキュメントが作成される、docsディレクトリはgh-pagesブランチのソースコードをサブモジュールとして追加したもので、詳しくは後ほど記載する

Doxygenのドキュメント

上記で記述したようにアプリケーションのソースコードはGitHubにあげたが、doxygenコマンドによって作成したドキュメントをGitHub Pagesにあげたことによって↓でドキュメントを確認できるようにした

ドキュメントURL:https://tomsato.github.io/doxygen-slim/

例えばクラス一覧よりControllerクラスとModelクラスがあることがわかる

サンプルを見て理解するDoxygenの書き方

ファイルコメントの書き方

SampleApp.phpより

/**
 * @file SampleApp.php
 * @brief サンプルのコントローラークラス(ファイルの簡単な説明を記述する)
 * @author tomsato
 * @date 2018/09/24
 * @details トップページ(GET: /)を表示するためためのクラスを持っている(ファイルの詳細な説明を記述する)
 */

クラスコメントの書き方

SampleApp.phpより

/**
 * @brief サンプルページを表示するためのコントローラークラス(クラスの簡単な説明を記述する)
 * @details 現在はトップページ(GET: /)を表示するための関数だけ持っている(クラスの詳細な説明を記述する)
 */

関数コメントの書き方

SampleApp.phpより

/**
     * @brief トップページ(GET: /)を表示するための関数(関数の簡単な説明を記述する)
     * @param request 引数の説明 - ex: requestインターフェース
     * @param response 引数の説明 - ex: responseインターフェース
     * @return 戻り値の説明
     * @detail モデルクラスから文字列を受けとってレスポンスを返す(関数の詳細な説明を記述する)
     */

変数コメントの書き方

//! 変数の説明①
$str = \Myapp\Model\SampleModel::getStr();

/**
 * 変数の説明②
 */
$request = [
    'hoge' => $str
];

コメントがどのようにドキュメントに書き起こされるか

例:Myapp\Controller\SampleApp クラス
こちらのページのようにドキュメント化される

GitHub Pages連携する

連携とは、GitHub Pagesとは

GitHub Pagesを使うとGitHubの「gh-pages」ブランチにアップロードした静的なソースコードをこちらのようにホスティングしてくれる

例えば
「tomsato」Organizationの
「doxygen-slim」Repositoryの
「gh-pages」ブランチにソースコードを乗せた場合に
「https://tomsato.github.io/doxygen-slim/」というURLでサイトを公開することができる、というもの

今回doxygen-slim Repositoryのmasterブランチでdocs/ディレクトリを用意したが、こちらはgh-pagesブランチをサブモジュールとして追加した

その証拠に、↑ではmasterブランチのソースコードで「docs @120fd34」と記述されていて、↓gh-pagesブランチの最新コミットログが「120fd34」なので、docsがgh-pagesへのリンクとなっていることがわかる

このようにするmasterブランチでアプリケーションのソースコードを修正しつつ、Doxygenコメントを修正したのちに、doxygenコマンドによってgh-pagesも同時に修正することができる

このやり方をこれから記載していく

連携準備

まず以下のようにDoxyfileに少し修正を行う

// src/以下のソースコードに対してだけドキュメントに起こしたいので
INPUT = src/

// アウトプットファイルはdocs/以下に作成したいので
HTML_OUTPUT = docs/

gh-pagesブランチを作成する

$ git branch
* master

$ git checkout --orphan gh-pages
$ git rm -rf .

空だとプッシュできないので適当なファイルをコミットしてからプッシュする

$ echo "My GitHub Page" > index.html
$ git add index.html
$ git commit -a -m "initial commit"
$ git push origin gh-pages

こうしたことによってGitHubにgh-pagesブランチが作成して、「https://(Organization名).github.io/(Repository名)/」が見れるようになったはず

gh-pagesブランチをサブモジュールにする

以下のコマンドでgh-pagesブランチのソースコードをサブモジュールとしてdocs/に追加する

$ git checkout master
$ git submodule add -f -b gh-pages `git remote -v|grep origin|head -n 1|awk '{print$2}'` docs

pushを忘れずに

$ git add -A
$ git commit -m 'add doxygen docs(gh-pages)'
$ git push origin master

ドキュメントを作成・更新する時

Doxygenのドキュメントを作成・更新する際はdoxygenコマンドを使って作成する

$ doxygen

docs以下が更新されたはずなので、gh-pagesブランチに更新分をプッシュする

$ git submodule foreach git add -A
$ git submodule foreach git commit -m 'submodule commit message'
$ git submodule foreach git push gh-pages

gh-pagesの最新のコミットログが変わったので、master側も最新のコミットログを見るように更新する

$ git add -A
$ git commit -m 'fix doxygen docs(gh-pages)'
$ git push origin master

注意点・できなかったこと

どの関数からどの関数を呼び出しているのかをグラフに可視化できるのだが

$model = new \Myapp\Model\SampleModel();
$str = $model->getStr();

とするとグラフに反映できずに表示されなかった…

$str = \Myapp\Model\SampleModel::getStr();

このようにstatic関数の呼び出しだと↓のグラフが作成される

何故前述の方法だとグラフ化されないのかが謎…
PHPならではの問題な気はするが他の言語でももしかしたらうまくグラフが生成されない場合があるかもしれない

Share

最近の投稿

NetlifyのSplit TestingとFunctionsについて使い方をまとめる Split TestingはGitHubのブランチをベースにしたA/Bテストを行うための機能のことで、FunctionsはNetlifyでAWS Lambdaを使うことができる

NetlifyとはHTMLなどの静的コンテンツのみで構成されたWebサイトを閲覧できる形で配信するWebサービス GitHubやBitbucket、GitLabなどと連携して使うことができて、リポジトリにプッシュすることで自動でCI/CDを行うことができる、無料枠が豊富で独自ドメインを設定可能

WordPressからJekyll(GitHub Pages)に移行した手順をまとめる。 お金的な事情や使いやすさなどの理由で無料のJekyll+GitHub Pagesに移行した。JekyllとはMarkdown等から静的ページを生成する静的サイトジェネレータ

Scala開発のためにScalaらしさをまとめる 言語設計者の設計思想を元にScalaらしさについてまとめる オブジェクト指向と関数型の融合について

StorybookとはUI開発環境を提供するツール React、React Native、Angular、Vueなどをサポートしている ユーザーは独立した開発環境でコンポーネントを個別に作成して挙動の確認をテストできたり、コンポーネントを一覧にしてカタログ化できるので他の人に紹介する時に使えたりする

カテゴリ一覧

タグ一覧