Документация

Автоматически использовать комментарии C++ для текста справки

Если эти общедоступные конструкции содержат комментарии C++, то MATLAB добавляет комментарии к описаниям MATLAB по умолчанию.

MATLAB читает стиль Doxygen, комментарии C++, но не является синтаксическим анализатором Doxygen. Например, MATLAB обрабатывает Doxygen @brief и @details для добавления содержимого к описанию класса или функции. MATLAB читает @param и @return для дополнения описаний аргументов. MATLAB использует содержимое @code для предоставления примеров кода. В любой команде Doxygen команда MATLAB игнорирует теги форматирования. Например, отображается синтаксический анализатор Doxygen word как показано в этом теге <b>word</b> полужирным шрифтом. MATLAB просто включает текст <b>word</b> в справке. MATLAB не отображает теги HTML <code>, ​</​code>, ​<p>, ​</​p>, и<br>.

По умолчанию MATLAB копирует комментарии C++ из заголовков библиотек и исходных файлов в Description и, при наличии, DetailedDescription аргументы для этих методов. Перечисления необязательно имеют EnumerantDescriptions аргументы. Просмотреть и изменить содержимое можно с помощью .mlx файл определения библиотеки.

Description, DetailedDescription, и EnumerantDescriptions аргументы принимают строковые значения. Текст в этих значениях можно обновить вручную. Например, может быть больше содержимого в .hpp чем MATLAB включает по умолчанию. Также может потребоваться включить примеры кода для сценария использования.

Если вы не хотите копировать комментарии C++ из заголовков и исходных файлов, то вызовите clibgen.generateLibraryDefinition с аргументом "GenerateDocumention false. Вы по-прежнему можете ввести текст в Description в файле определения.

Вручную обновить текст справки

В этом примере используется интерфейс, встроенный в библиотеку C++ только в заголовок. Другие примеры см. в разделе Справка по изменению библиотеки.

При создании интерфейса перейдите в папку с defineschool.mlx файл и 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.mlx. Поиск текста 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.mlx. Удалите существующий файл интерфейса.

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

Сравнить созданную справку с комментариями к заголовкам

Пример, описанный в справке по изменению библиотеки, показывает созданную справку для XMLPlatformUtils.Initialize метод в библиотеке анализатора Apache™ Xerces-C ++ XML. Это содержимое происходит из проекта Apache Xerces, https://xerces.apache.org, и лицензируется по лицензии Apache 2.0, https://www.apache.org/licenses/LICENSE-2.0.

MATLAB использует комментарии C++ в PlatformUtils.hpp файл.

    /** @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()

    No outputs