MQL5ソースコードに基づくドキュメントの作成

はじめに

開発者はしばしばコードのドキュメントを作成する必要があります。説明書とユーザーマニュアルの作成は、日々の活動と顧客とのコミュニケーションの不可欠な一部です。さらに、時間とともに、複数の開発者によって書かれたさまざまなライブラリやコードスニペットが蓄積され、うまく構造化されたドキュメントは、それらをより簡単に理解するのに役立ちます。コードを開発するときに、マニュアルを書く必然性を念頭に置けば、この作業には時間がかかりません。必要なコメントとタグはコード作成と同時に追加されます。この作業は一見すると不必要に思えるかもしれませんが、後に開発者の多くの時間と労力を節約することになります。

ドキュメントの作成プロセスを一通り考えて、最も重要な点を詳細に分析しましょう。以前に関連記事が書かれましたが、そこに記載されている情報や方法の一部にはもはや意味がありません。このトピックをさらに発展します。主にDoxygenソフトウェアとDoxywizard.exeの使用を考察します。

DoxygenへのMQLファイルの追加

ここでの目標は、準備されたマークアップを使って、ファイル（1つまたは複数）に既に書かれたコードに基づいてヘルプ/プレゼンテーションファイルを作成することです。作成されるのはchm形式のファイルです。さらに、プレゼンテーションや参照の目的にも適しているhtmlファイルを作成します。Doxygenソフトウェアはこれらの作業に適しています。

プログラムの設定プロセスと作成されるファイルは、上記の記事に説明されています。この記事はかなり前に発表されたので説明が正しくなく、それに従うと、プログラムは警告とエラーメッセージなしで実行されますが、ファイルが作成されません。

したがって、最初に行う必要があるのは、プログラム構成の記述を更新することです。doxywizard.exeを起動して、プロジェクトの名前と入出力フォルダを指定して、Wizard（ウィザード）タブのMode（モード）セクションの "Optimize for C++ output"（C++の出力に最適化）オプションがチェックされていることを確認します。

Expert （エキスパート）タブを開き、必要な拡張子を持ったファイルを Input （インプット）セクションに追加します。

これで、Doxygenは特定の拡張子を持つファイルを解析する必要があることを知ります。しかし、これでは十分でありません。 .mq * 拡張子を持つファイルが .с拡張子を持つファイルと類似していること、すなわちファイルがマップされていることをプログラムに明示的に指示しなければなりません。

これでDoxygenはファイルの解析と結果の生成を開始します。

符号化

前の記事で扱われていなかったあと一つの問題は、ソースとその結果のドキュメントの符号化に関連したものです。

ドキュメントの言語が英語の場合、問題はありません。しかし、別の言語でドキュメントを作成したい場合は、文字抜けが生じる場合があります。その理由は次のとおりです。すべてのドキュメントは、デフォルトでUTF-8符号化で作成されたものとみなされます。ドキュメントの一部に異なるエンコーディングがあると、テキストが判読できなくなる可能性があります。以下で解決策をみてみましょう。

1. デフォルト言語とエンコーディングを決定します。ここではUTF-8とロシア語を使用します。
   

   
   

   
   

   DOXYFILE_ENCODINGはそのままであることにご注意ください。UTF-8はこの入力フィールドで指定されているエンコーディングに関係なく追加されます。おそらく、ここでエンコーディングを変更する唯一の方法はファイルに明示的に指定して、 "Head"を置き換えることですが、これでは望みの結果は達成できません。
   

2. ソース文書のエンコーディングを指定する必要があります。これはUTF-8と異なる場合があり、この例ではCP1251です。ソースドキュメントによってエンコーディングが異なる場合、すべてのソースドキュメントが単一のエンコーディングを使用するようにエンコーディングを変更する必要があり、それをこの入力フィールドで指定する必要があります。
   

   
   

3. 出力はCHM形式なので、HtmlHelpインデックス（hhk拡張子を持つファイル）で使用されるエンコーディングを明示的に指定する必要があります。
   

   
   

   このプロセスをより詳細に理解したい方のために、以下にDoxygenを使用してスペイン語と英語のドキュメントを作成する方法に関する記事を添付しました。

さて、生成されたhtmlファイルの外観といった、より一般的な点について説明しましょう。これが最も重要に思えます。

ページヘッダーとページフッター

利用機能なオプションはExpertタブのHTMLセクションにあります。ここで便利なツールは、カスタムHTMLファイルを、最終的なドキュメント（HTML_HEADER、HTML_FOOTER、HTML_STYLESHEETなど）の作成に使うためのスイッチャーです。それが各ページのヘッダーに使われるか各ページのフッターに使われるか、及びその表示スタイルは、フィールド名に基づいて理解することができます。htmlファイルを生成するには、このタブでGENERATE_HTMLスイッチをオンにすることを覚えておいてください。

解析されたhtmlファイルは両方とも特別なルールに基づいて書かれていますが、footer.htmlではヘッダーやスタイルを使わないhtmlテキストを使いました。

<div>
  <h1 style="text-align: center;">Footer</h1>
</div>

しかし、規則に従う方が良いでしょう。カスタムファイルの配置方法を理解するためには、プログラムで使用されるデフォルトのファイルを生成することができます。必要な2つのhtmlファイルに加えて、スタイルシートも生成します。次のコマンドを使ってやってみましょう。

 - doxygen -w html new_header.html new_footer.html new_stylesheet.css

下記はnew_footer.htmlファイルの一部です。

<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function!-->
  <ul>
    $navpath
    <li class="footer">$generatedby
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
  </ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> $doxygenversion
</small></address>

ここでは数多くのプレースホルダーが見られますが、その一覧と目的はドキュメントに記載されています。Doxygen広告が表示される場所とリンク先を正確に理解するのは簡単です。同様に、new_header.htmlと必要に応じてスタイルシートを編集し、指定したタブで有効にすることができるので、作成されたドキュメントの外観は大幅に変更することができます。

前処理

Doxygenではファイルの前処理が可能で、BEGIN_MESSAGE_MAPやVisual Studioの__declspecのようなマクロも処理されます。私たちのスクリプトではこれはそれほど重要ではないので、ここでは詳細については説明せずにその可能性のみをで言及することにします。このメカニズムは、ExpertタブのPreprocessorセクションで設定します。外部フィルタの作成も可能です。これらのフィルタの目的は、Doxygenが理解できるように入力ファイルを変換することです。このようなフィルタは外部コンソールプログラムで、処理されたファイルの名前がコマンドラインに追加されます。フィルタプログラム自体は、基本的に、アセンブラー内のプログラムをDoxygenが理解できる形式に変換する正規表現のセットです。開発者は前処理を適用するかどうかを決定する必要があります。例として、このメカニズムは、Doxygenが理解できるように#propertyの構造を変換するために使用することができます。

例の含み方

ドキュメントに例を含むことは非常に興味深い可能性です。例は必須ではありませんが、含むことによってドキュメントは完全かつプロフェッショナルに見えます。例は1つ以上のファイルとしてプロジェクトに含まれています。これを行うには、例を提供したいコードのページに以下を追加します。

/** \example filename.ext
 * これは、使用方法の例です ....
 */

ここには例のあるファイルの名前が設定されています。2行目では、例に示す関数またはクラスを一覧することができます。しかし、これでは不十分です。ファイルがどこにあるかはまだ分かりません。例を含むファイルへのパスをDoxygenで明示的に指定する必要があります。ファイルへのパスとファイル名のパターンを指定されるので、下の図を参照してください。

いくつかのパスを追加してEXAMPLE_RECURSIVEチェックボックスを使用することで、複数の例ファイルを含んだ、構造化されたヘルプ文書を生成することができます。

HTMLタグ

Doxygenのもう一つの便利な機能は、コメントブロックに直接置いたhtmlマークアップを扱う可能性です。プログラムのドキュメントには、Doxygenが処理して最終的な文書に挿入できる、実質的なhtmlタグの一覧があります。たとえば、次のテキストは、リンクとタイトルの付いた表をマクロ記述に挿入します。

/*!
  \def def_example
  \brief <a href="http://www.google.com">links to google</a>
         <table>
           <caption>Single table</caption>
           <tr>
             <td>One</td>
             <td>two</td>
           </tr>
         </table>
*/
#define def_example "Some define"

htmlのマークアップでは  のような擬似文字を使うことができます。

あと1つは自動リンク生成というリンクの使用に関連する興味深い機能です。これは実際には、Doxygenがhttps://www.mql5.comのようなテキストを正しいリンクに変換して、生成されたドキュメントに挿入することを意味します。自動リンク生成は、ファイル、クラス、および個々の関数へのリンクを作成することもできます。これは、「参照」などのセクションを生成するのに便利な機能です。一般的に、これらのマークアップの可能性は、コードフラグメントのより良い説明を提供し、 "前/次"マークアップやその他のページングフォームに使用することができ、またSEOや広告目的にも使用できます。

タイトル/カバーページ

ページのヘッダーとフッターのコードを独自のテキストに置き換える機能についてはすでにお話ししましたが、加えて、タイトルページのために別のデザインを開発することも可能です。このためには、ファイルの1つにタイトルページが含まれていることを指定する必要があります。これはファイルの冒頭に \mainpageタグを含むことで行います。

/*!\mainpage My Personal Index Page
* \image html i.jpg
 */

このマークアップは、ファイルが存在するファイルがタイトルページであり、タイトルが "My Personal Index Page"であり、その後に画像"i.jpg"が続くことを宣言します。画像は事前に準備しておく必要があり、そのパスはDoxygenに知られていなければなりません。

画像に加えて、他の種類のファイルを挿入することもできます。

htmlとHtmlHelpのドキュメント

ドキュメントはいくつかの形式で作成できます。必要な形式は WizardタブのOutputセクションで、確認できます。最初のオプションは通常のhtml形式です。index.htmlファイルは、指定された出力フォルダに作成され、ドキュメント全体のメインファイルになります。しかし、この形式は必ずしも便利ではないので、HtmlHelp形式でドキュメントを作成することを検討しましょう。Output メニューでHTMLと"prepare for compressed HTML"（圧縮されたHTMLの準備）を選択します。さらにExpertタブ→ HTML →CHM_FILE入力フィールドで、HtmlHelpのファイル名を拡張子つきで設定し、下（ HHC_LOCATION）で、 hhc.exeヘルププロジェクトコンパイラへのパスを指定します。このパラメータは任意で、フィールドが空白の場合、プログラムは必要なファイルをすべて準備し、HTML Help Workshopを使用してchm形式でのヘルププロジェクトも生成します。

Outputメニューには、微調整のためのオプションもいくつか用意されています。GENERATE_CHIには特別な注意が必要です。このオプションはデフォルトで無効になっており、有効にされるとDoxygenはCHI拡張子を持ったインデックスファイルを生成します。このファイルを削除すると、メインヘルプファイルを使用する際に問題が発生する可能性があります。HtmlHlp形式のヘルプのほとんどは、ほとんどの機能を失います。

エンコーディングオプションについては既に説明したので、Run（実行）タブに移動してRun Doxygen（Doxygenを実行）を押すだけです。技術的なメッセージを含むページが表示された後にDoxygen は操作の完了を報告します。下のShow HTML output（HTMLを表示）ボタンをクリックすると、生成されたドキュメントをブラウザで見ることができます。HtmlHelp形式のファイルは手動で実行されるべきです。

下記はDoxywizardの使い方に関する短いビデオです。

次に、いくつかのマイナーな点について検討しますが、これも興味深いものです。

Sublime Text 3エディタでのMQL5コードタグ付けの可能性

適切なDoxygen操作のためには、ドキュメントのテキストに特殊タグを使用する必要があります。タグは、コード、クラス、マクロ、関数などの別々の部分の複数行および単行のコメントに配置されます。ドキュメントに追加したい情報が多くなればなるほど、それをより慎重に構造化する必要があるので、タグ構造はより複雑になります。

タグはMT5エディタで追加できます。この場合、すべてのエラーを慎重に監視する必要があります。このプロセスはわずかに単純化し、部分的に自動化することができます。Sublime Text 3エディタを使いましょう。これはMQL4を認識し、MQL5でも動作します。エディタでMQLに関連する両方のパッケージを有効にします。

次に、必要なマークアップを使用するために、DoxyDoxygenパッケージをインストールします。これにはホットキーがあり、異なる言語に翻訳する可能性を提供するだけでなく、自動完成機能も含まれています。このパッケージは、適切なタグをより迅速かつ低コストで配置するのに役立ちます。ドキュメント（本稿添付）は、マークアップ後、エディタから直接Doxygenを呼び出すことができることを示唆しています。パッケージ構成プロセスの説明は、以下の添付ファイルでも参照できます。

一般的に、記述されたパッケージを使用することには特に問題がないので、詳細には触れません。

pdfとdjvuの出力

Doxygenはこの興味深い機能を提供しますが、その実装はまだ完了していません。それにもかかわらず、これらの形式でのドキュメントの出力を試みることができます。関連情報はDoxygenのドキュメントで提供されていますが、サードパーティのWebサイトにも関連する記事や説明があります。pdfの出力を考えてみましょう。

1. WizardタブのOutputのポイントでLaTeX出力を選択してfor PDFを選択します。ドキュメントにはPerlModのExpertタブで GENERATE_PERLMODEを選択する必要もあると書いてありますが、このステップはスキップします。
2. CHMとhtmlの出力を含む他の必要な設定を構成します（必要な場合）。
3. 文書を作成します。

latexフォルダが出力フォルダに作成され、適切なファイルが作成されます。Doxygenソフトウェアのドキュメント作成手順はこれで終わりなので、latexファイルをPDFに変換する必要があります。これにはここのMikTexソフトウェアのポータブル形式を使用しました。インストールし、プログラムを実行します。TeXworksを選びます。latexフォルダでDoxygenによって作成されたrefman.texをエディタウィンドウで開きます。エディタのツールバーで、一覧からXeLaTexを選択し、左側の大きな緑色のボタンをクリックします。その後、いくつかの診断メッセージが表示されます。エディタは作業中にインストール用の追加パッケージを提供します（同意する必要があります）。出力でエラーが発生した場合は、もう一度ドキュメントをコンパイルしてみてください。

結果として、ドキュメントを含むrefman.pdfファイルが同じlatexフォルダに作成されます。ただし、出力品質にはあまり期待できず、ドキュメントデザインも編集する必要があります。おそらく、ソースラテックファイルを編集することによって、多くの小さな欠陥を避けることができるでしょう。しかし、この可能性の実装はまだ完了していないので、Doxygenでこのオプションが公式に紹介されるのを待つことにしましょう。

適用

例に移り、Doxygenなどのドキュメンテーション関連のソフトウェアの使い方を見てみましょう。標準ライブラリのドキュメント、つまり \MQL5\Includeのクラスのセットから始めましょう。ここでは、これらのファイルにタグを追加することなく、DoxyGenのすべてのファイルを処理するという単純な方法を使用します。ライブラリ要素についての追加的な重要な情報は取得できませんが、その結果を見ることもでき、これで十分な場合もあります。まず、すべての必要なソフトウェアコンポーネントがすでにコンピュータにインストールされていると仮定しましょう。さあ、始めましょう。

スタンダードライブラリを他のフォルダにコピーします。ただし、ファイルには何も書き込めません。

• Doxygenを実行して設定します。プリセットには付属のMQL5Doxygen.zipファイルを使用することができます。独自のファイルを使用する場合は、それに応じてDoxygenを再構成する必要があります。ファイルの必須パス、プロジェクト名、エンコーディングと言語を確認します。
  
• WizardタブとOutputセクションには特にご注意ください。出力フォーマットは"With search function"（検索機能付き）でプレーンhtml に設定されています。つまり、ウィザードは HtmlHelpファイルを生成しません。"prepare for compressed HTML (.chm)（圧縮されたHTMLの準備）を選択すると"With search function"（検索機能付き）オプションのチェックは外されませんが、プログラムはのちにオプションが使用できないとの警告を表示します。しかし、両方のオプションが必要です。
  
• したがって、生成プロセスを2回実行する必要があります。1番目の生成はMQL5Doxygen.zipからの簡単な設定を使用し、出力フォルダにはhtml 形式のドキュメントのみが提供されます。ドキュメントの初めはindex.htmlに配置されています。
  
• 他の設定で生成を繰り返します。"With search function"（検索機能付き）のチェックを外し、"prepare for compressed HTML (.chm)"（圧縮されたHTML（.chm）の準備）をチェックします。Expert（エキスパート）タブに移動し、HTMLをポイントします。HtmlHlpヘルプファイルを作成するCHM_FILE、つまりWITH EXTENSIONというファイル名と、HHC_LOCATIONでのhhc.exeへのパスを設定する必要があります。これらの変数が初期化されていない場合、DoxygenはソースファイルをHtmlHlpプロジェクトのために準備しますが、ヘルプファイルを作成することはできないため、HTML Help Workshopの実行が必要です。必要な設定を変更すると、生成プロセスを開始できます。結果的にhtml f形式のドキュメントとHtmlHlp形式のヘルプドキュメントが提供されます（最初の起動時と同様ですが、検索オプションなしで）。結果と設定ファイルはStandardLibrary.zip 添付ファイルにあります。このファイルからhtml ファイルが削除されます。 html形式の標準ライブラリのマニュアルが必要な場合は、簡単に作成できます。
  

次の例を考えてみましょう。今回は、必要なタグを追加し、生成されるファイルの外観の改善を試みます。

• まず、最も単純なテストコードを持つ2つのファイルを作成し、それを「複雑」にします。必要なタグをつけてカバーページmainpage.mq5を作ってみましょう。さらに、このタイトルページに画像を追加します。3つのファイル（画像ファイルを除く）はWizardタブのProjectセクションでソースコードディレクトリ として定義されたフォルダに配置されます。ここでは、必要に応じて出力フォルダとプロジェクトのロゴも定義します。
• 画像用のフォルダを作成し、画像ファイルを保存してみます。 Doxygen でフッターとして使用するファイルを編集してfooter.htmlファイルを作成します。目的は Doxygenの広告を削除することです。ここに別のものを追加することもできますが、 "is needed for treeview function!"（ツリービュー機能のために必要です）というファイルの警告は、編集中に気をつけなければならないことを示唆しています。設定を変更し、画像の場所と新しいページフッターファイルを指定しましょう。このプロセスは先に説明しました。
• このコードを使用してテストサンプルで1つのファイルを作成し、それを別のフォルダに保存し、Doxygenにその場所を通知します。
  
• プロジェクト構造を作成したので、テストコードでファイルを開き、必要なタグを追加することができます。Sublime Text 3は、インストールされたパッケージセット（記事の冒頭に記載されています）で使用します。添付されたアーカイブにはマークアップバージョンの1つが含まれていますが、他にも多くのバリエーションがあります。
• Doxygenの設定を最後に変更します。前の例で説明したように、2段階の出力を実行する可能性を提供する必要があります。
  
• 出力を実行します。その後HTML形式のドキュメントを受け取り、Doxygenの設定を変更して、HtmlHelp の形式でドキュメントを受け取ります。

プロジェクト全体、ソースファイル、Doxygen設定ファイル、および両方の形式で作成されたドキュメントは添付の Custom_HTML_CHM.zip アーカイブで参照できます。

終わりに

本稿の目的は、ドキュメントの引用を避けて代わりに様々なプログラムを使用し、魅力的なドキュメントを生成するさまざまな特定の機能に焦点を当てることです。Doxygenのすべてのタグとスイッチについて詳しく調べたい方のために、既存のソフトウェアのドキュメントがCHM 形式で添付されています。Sublime Text 3パッケージにはビルトインのドキュメントが用意されており、このエディタは非常に人気があります。

添付ファイルの説明

名称	説明
Using_Doxygen_to_generate_Spanish_and_English_documentation.zip	pdf形式の記事
Doxygen_Manual.zip	chm形式のDoxygenドキュメント
DoxyDoxygen.zip	pdf形式のDoxyDoxygenパッケージドキュメント
MQL5Doxygen.zip	Doxygen設定ファイル
StandardLibrary.zip	CHM形式で生成されたドキュメント
Custom_HTML_CHM.zip	HTML形式およびCHM形式で生成されたドキュメント