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

Автоматическое использование комментариев 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 файл определения библиотеки.

The Description, DetailedDescription, и EnumerantDescriptions аргументы берут строковые значения. Вы можете вручную обновить текст в этих значениях. Для примера может быть больше содержимого в .hpp файл, который MATLAB включает по умолчанию. Или вы, возможно, захотите включить примеры кода для вашего примера использования.

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

Обновление текста справки вручную

Этот пример использует интерфейс, созданный в Publish Interface to Header-Only C++ Library. Другие примеры см. в разделе «Изменение справки по библиотеке».

Если вы создали интерфейс, перейдите в папку с 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