MQL5 コード用自動作成ドキュメンテーション

1. はじめに

Java プログラマーの多くは JavaDocs により作成することのできる自動作成ドキュメンテーションを熟知されていることと思います。その考え方は、検索が簡単なヘルプファイルに抽出できる半構造法によりコードにコメントを追加するというものです。

C++ 言語界にもまたドキュメンテーション自動作成機能があります。 Microsoft の SandCastle と Doxygen が代表的な2つです。私は Doxygen がどれほどうまくを文書化するか確認しようと思いました。MQL5は、実質的にはカスタマイズされた C++言語のサブセットです。私にとってはこれは MQL5 の成長において重要なステップなのです。なぜなら言語の複雑性がきわめて大容量のクラスライブラリを簡単に発展させることができるからです。

実験はひじょうにうまくいきましたから、Doxygen が MQL5 コードから作り出すヘルプのドキュメンテーションは大きな価値を加えると信じています。

2. Doxygen

Doxygen はオープンソースの自動ドキュメンテーション作成機能で、GNU General Public License下で利用可能です。それがLinux や Mozilla といったその他のオープンソースプロジェクトと同様に開発されていることを意味します。Doxygen は無料でダウンロードし使用することができます。そのソースコードは誰にでも閲覧可能です。またそれは時間を無償で提供する数多くの開発者が協働して開発し強化しています。

利用にあたり、もっとも基本レベルでは Doxygen はプロジェクト内ですべての C++（また MQL5）言語コードをパースし、検索しやすいヘルプファイルでストラクチャを表示しています。これは「オブジェクト指向」のコードセットでは特に有用です。それは広範なクラス階層と数多くのメンバ関数を持つものです。Doxygen 機能をフルに利用するにはコードに構造化されたコメントを書き、Doxygen がそれらを読み、作成されたヘルプファイルに情報を追加できるようにします。

2.1Doxygen のダウンロード

Doxygen のホームページです。 http://www.doxygen.org/　そこからページをダウンロードするを検索し、Windows 向け最新バージョンをダウンロードすることができます。本稿執筆時は doxygen-1.6.1でした。下図を参照ください。

図1　Doxygen のダウンロード

2.2Doxygenのコンフィギュレーションと実行

ほとんどなにもすることはありません。ファイルタイプ *.mqh および *.mq5 を追加し、HTML ヘルプの作成時に入れ替えるだけです。コンフィギュレーション中以下の5図に表示されている内容が実行されます。

スクリーンショットの最初の4個（図2～5）は「ウィザード」画面で実行されます。

図2　Doxygen のコンフィギュレーション－ウィザード1

図3　Doxygen のコンフィギュレーション－ウィザード2

図4　Doxygen のコンフィギュレーション－ウィザード3

図5　Doxygen のコンフィギュレーション－ウィザード4

最後に1個エキスパートレベルで変更し、ファイルタイプ mqh および mq5 を追加します。

図6　Doxygen のコンフィギュレーション－mqh および mq5のインクルード

これで実行準備が整いました。Doxgyen はコンフィギュレーションファイル内で格納と読み出しを行うことに注意が必要です。このファイルは本稿に添付の zip ファイルにインクルードされています。

図7　Doxygenの実行

2.3Doxygenを使用する

Doxygen は優れたコンパイル済み html ヘルプファイル（もちろんDoxygenで構造化されています。ここにオリジナルバージョンがあります）を持ちます。それは複雑な数式を完璧に表示する機能を含む驚くべきドキュメンテーション機能の配列を詳述しています。ただし、このツールはまたひじょうにシンプルな方法で利用され、便利なヘルプファイルを作成します。

ここに MQL5/Include/Oscilators.mqh の CiMACD::Create() 関数例があります。これら「インディケータ」ファイルはもともと初期のβ版配布ではないことに注意が必要です。よってそれらを見るには MetaTtrader 5 を再ダウンロードする必要があります。

//+------------------------------------------------------------------+
//| Create indicator "Moving Averages Convergence-Divergence".       |
//| INPUT:  symbol          -chart symbol,                           |
//|         period          -chart period,                           |
//|         fast_ema_period -period fast EMA,                        |
//|         slow_ema_period -period slow EMA,                        |
//|         signal_period   -period signal MA,                       |
//|         applied         -what used.                              |
//| OUTPUT: true-if successful, false otherwise.                     |
//| REMARK: no.                                                      |
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

キーワードにいくつか簡単な変更を加えると Doxygenで解釈するためのコメントが準備できます。ここでコメント部は3本スラッシュ (///)、INPUT: は \param に、OUTPUT: は \return に変更されています。

//+------------------------------------------------------------------+
/// Create indicator "Moving Averages Convergence-Divergence".        
/// \param  symbol          -chart symbol,                            
/// \param  period          -chart period,                            
/// \param  fast_ema_period -period fast EMA,                         
/// \param  slow_ema_period -period slow EMA,                         
/// \param  signal_period   -period signal MA,                        
/// \param  applied         -what used.                               
/// \return true-if successful, false otherwise.                      
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

その後 Doxygen がそれを処理するとき、ヘルプファイルは図8のように表示されます。

図8　Doxygen-generated HTMLに表示されるCiMACD::Create()

2.4 配布された MQL5 コードセット全体で Doxygen を利用する

Doxygen がもっとも力を発揮するのは大規模プロジェクトに対してヘルプファイルを作成するときです。MQL5 フォルダでMetaTrader 5と共に配布さるので、フォルダには100 もの .mq5 および .mqh ファイルがあり、それらの多くは相互連携しています。

私は上で概説されたDoxygen コメント変換に対し、基本的なMetaquotesを処理するユーティリティスクリプト MetaquotesCommentsToDoxygen.mq5 （添付の zip ファイルにインクルードされています）を書きました。これはヘルプファイル作成の基本ステップではありませんが、Doxygenの便利な付加的ドキュメンテーション機能を示すものです。

MQL5 コードセットヘルプファイルを作成する手順は以下のようなものです。

• MQL5/filesに MQL5 フォルダとサブフォルダをコピーする。
• MQL5/files/MQL5/Include/Strings/string.mqh を消去する。なんらかの理由によりこのファイルは Doxygen がコードパースを行うのを妨げるためです。

構造化されたコメントからの追加ドキュメンテーションのオプション

• MQL5/Files フォルダから Windows/DOS コマンド xcopy *.mq* c:\ /S/L > MQL5codeList.txt を実行します。
• 任意のチャート上で MetaquotesCommentsToDoxygen.mq5 スクリプトを実行します。

結果得られたヘルプドキュメンテーションはクオリティーがよくその利便性を素早く示します。図9～図12は閲覧サンプルです。

図9　Doxygen 作成クラスリスト

図10　CArrayObj 向けDoxygen作成クラス階層図

図11　CArrayObj 向けDoxygen作成メンバ関数リスト

図12　Doxygen 作成定義リスト

3. Microsoft の HTML ヘルプワークショップ

Doxygen からより有用なアウトプットを作成するために必要なステップがもう一つあります。Doxygen はその他 html ファイルや描画を大量に示すindex.htmlファイルを作成します。それは基本的には小さなウェブサイトで、そのため配布はひじょうに面倒です。

ずいぶん以前、マイクロソフト社 は Windows のアプリケーション向けヘルプファイルは html 形式で書くべきだとしました。そのため独自の「HTML ヘルプワークショップ」を開発しました。「HTML ヘルプワークショップ」は Doxygen からのアウトプットのようなヘルプファイルセットを取り、それを一つの .chm ファイルにコンパイルします。これは MetaTrader 5 と共に配布されるヘルプファイルと同じ形式です。

3.1HTML ヘルプワークショップをダウンロードする

このマイクロソフトページからhtmlhelp.exe をダウンロードすることができます。

図13　HTML ヘルプのダウンロード

3.2 コンパイル済み HTML ヘルプファイルの作成

処理を行っている Doxygen からのアウトプットは「HTMLヘルプワークショップ」によって簡単にコンパイル済み html ファイルに変換することができます。本稿のために構成され、下図14にあるように Doxygen は「HTMLヘルプワークショップ」のために準備された index.hhp ファイルを作成します。

図14　Doxygenによって作成されるindex.hhpファイルのロケーション

 次のステップはコンパイルです。

図15　HTML ヘルプによるコンパイル

そしてそれが終わると、新しい index .chm ファイルがMetaTrader 5/Helpフォルダにコピーされ、名前がつけなおされます。それは図16、図17に示されています。

図16　index.chm ロケーション

図17　ヘルプフォルダにコピーされ、名前がつけなおされたindex.chm

4. サマリー

この練習により、みなさんに理解し利用していただきたいと思うあらゆるMQL5コードを文書化するため、将来的に Doxygen やその類似品を使うことを確信しました。他の人も同じように考えてくれると良い思います、

付録添付の Doxygen files.zip にあるファイル内容

ファイル	内容	コピー先
MQL5 codeset help.chm	2009年12月8日、MetaTrader 5 ビルド 229と共に配布されたすべてのコードのコンパイル済み HTML ヘルプファイル	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Doxygenが解釈できるようにするための MQL5コードでのコメントを変更するスクリプト	MQL5/Scripts
MQL5codeList.txt	配布済み全 MQL5 ファイルリスト	MQL5/Files
MQL5_Doxygen	Doxygen コンフィギュレーションファイル	MQL5