C++ ライブラリに対する MATLAB インターフェイスのヘルプ テキストのパブリッシュ
インターフェイスをパブリッシュすると、関数 clibgen.generateLibraryDefinition
は、C++ ヘッダー ファイルのコメントと、クラスと関数に関する他の既定のテキストを挿入します。関数 doc
はこのテキストをユーザーに表示します。ライブラリ定義ファイルを編集して、C++ コメントの挿入およびテキストの変更を無効にすることができます。
ヘルプ テキストのための C++ コメントの自動使用
以下のパブリックな構成に C++ コメントが含まれている場合、MATLAB® はそのコメントを既定の MATLAB の説明に追加します。
関数および引数
メンバー関数および引数
クラスおよび構造体
データ メンバー
列挙型および列挙値
クラスのテンプレート関数およびテンプレート メソッド
MATLAB は、Doxygen スタイルの C++ コメントを読み取りますが、Doxygen パーサーではありません。たとえば、MATLAB は Doxygen の @brief
コマンドと @details
コマンドを処理して、内容をクラスまたは関数の説明に追加します。MATLAB は @param
コマンドと @return
コマンドを読み取って、引数の説明を増補します。MATLAB は @code
コマンドの内容を使用して、コード例を提供します。MATLAB は、Doxygen のコマンド内にある書式設定タグを無視します。たとえば、Doxygen パーサーは、タグ <b>word</b>
で示されるような word
を太字フォントで表示します。MATLAB では <b>word</b>
というテキストがヘルプに含まれるだけです。MATLAB で、<code>
、</code>
、<p>
、</p>
、<br>
の各 HTML タグは表示されません。
MATLAB は既定で、ライブラリのヘッダー ファイルとソース ファイルから C++ コメントを、以下のメソッドの Description
引数と DetailedDescription
引数 (ある場合) にコピーします。列挙型はオプションで EnumerantDescriptions
の引数を取ります。ライブラリ定義ファイルを使用して、内容の確認と編集ができます。
Description
、DetailedDescription
および EnumerantDescriptions
の各引数は string 値を取ります。これらの値に含まれるテキストを手動で更新できます。たとえば、MATLAB が既定で含めるものより多くの内容が .hpp
ファイルに存在する場合があります。あるいは、使用例にコード例を含めるとします。
ヘッダー ファイルとソース ファイルから C++ コメントをコピーしない場合は、引数GenerateDocumentationFromHeaderFilesを false
に設定して clibgen.generateLibraryDefinition
を呼び出します。定義ファイルの引数 Description
に引き続きテキストを入力できます。
ヘルプ テキストの手動更新
この例では、ヘッダー専用の HPP ファイルでビルドしたインターフェイスを使用します。他の例については、ライブラリのヘルプの変更を参照してください。
インターフェイスを作成した場合は、ファイル defineschool.m
をもつフォルダーおよびインターフェイス ライブラリをもつ school
フォルダーに移動します。あるいは、インターフェイスを作成します。
copyfile(fullfile(matlabroot,"extern","examples","cpp_interface","school.hpp"),".","f") clibgen.generateLibraryDefinition("school.hpp") build(defineschool) addpath("school") summary(defineschool)
クラス Person
の既定のヘルプ テキストは Representation of C++ class Person
です。ヘルプを表示するには、次を入力します。
doc clib.school
Classes contained in clib.school: Person - clib.school.Person Representation of C++ class Person Teacher - clib.school.Teacher Representation of C++ class Teacher Student - clib.school.Student Representation of C++ class Student
このテキストを変更するには、defineschool.m
を編集します。Representation of C++ class Person
を検索します。
"Description"
値を変更します。変更対象:
"clib.school.Person Representation of C++ class Person."
これを次のように変更します。
"clib.school.Person Class defined by name and age."
ファイルを保存します。
ライブラリをリビルドするには、MATLAB を再起動します。defineschool.m
が含まれるフォルダーに移動します。既存のインターフェイス ファイルを削除します。
delete school\*.dll
インターフェイスをビルドしてパスを更新します。
build(defineschool)
addpath school
更新されたヘルプを表示します。
doc clib.school
Classes contained in clib.school: Person - clib.school.Person Class defined by name and age Teacher - clib.school.Teacher Representation of C++ class Teacher Student - clib.school.Student Representation of C++ class Student
生成されたヘルプとヘッダー ファイルのコメントの比較
ライブラリのヘルプの変更で説明されている例は、Apache® Xerces-C++ XML パーサー ライブラリ内の XMLPlatformUtils.Initialize
メソッドについて生成されたヘルプを示します。この内容の出典は Apache Xerces プロジェクト (https://xerces.apache.org) であり、Apache 2.0 ライセンス (https://www.apache.org/licenses/LICENSE-2.0) によりライセンスが許諾されています。
MATLAB はファイル PlatformUtils.hpp
内の C++ コメントを使用します。
/** @name Initialization and Panic methods */ //@{ /** Perform per-process parser initialization * * Initialization <b>must</b> be called first in any client code. * * @param locale The locale to use for messages. * * The locale is set if the Initialize() is invoked for the very first time, * to ensure that each and every message loader, in the process space, share * the same locale. * * All subsequent invocations of Initialize(), with a different locale, have * no effect on the message loaders, either instantiated, or to be instantiated. * * To set to a different locale, client application needs to Terminate() (or * multiple Terminate() in the case where multiple Initialize() have been invoked * before), followed by Initialize(new_locale). * * The default locale is "en_US". * * @param nlsHome User specified location where MsgLoader retrieves error message files. * the discussion above with regard to locale, applies to nlsHome as well. * * @param panicHandler Application's panic handler, application owns this handler. * Application shall make sure that the plugged panic handler persists * through the call to XMLPlatformUtils::Terminate(). * * @param memoryManager Plugged-in memory manager which is owned by the * application. Applications must make sure that the * plugged-in memory manager persist through the call to * XMLPlatformUtils::Terminate() */ static void Initialize(const char* const locale = XMLUni::fgXercescDefaultLocale , const char* const nlsHome = 0 , PanicHandler* const panicHandler = 0 , MemoryManager* const memoryManager = 0);
例でインターフェイスをビルドした後、MATLAB のInitialize
メソッドのヘルプを表示します。
help clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize
clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize Method of C++ class xercesc_3_1::XMLPlatformUtils. Perform per-process parser initialization This content is from the external library documentation. Initialization <b>must</b> be called first in any client code. Inputs locale read-only string locale The locale to use for messages. nlsHome read-only string nlsHome User specified location where MsgLoader retrieves error message files. the discussion above with regard to locale, applies to nlsHome as well. panicHandler clib.MyXercesLibrary.xercesc_3_1.PanicHandler panicHandler Application's panic handler, application owns this handler. Application shall make sure that the plugged panic handler persists through the call to XMLPlatformUtils::Terminate(). memoryManager clib.MyXercesLibrary.xercesc_3_1.MemoryManager memoryManager Plugged-in memory manager which is owned by the application. Applications must make sure that the plugged-in memory manager persist through the call to XMLPlatformUtils::Terminate()
参考
clibgen.generateLibraryDefinition
| build