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()

参考

|

トピック