Publish Help Text for MATLAB Interface to C++ Library

When you publish an interface, the clibgen.generateLibraryDefinition function inserts C++ header file comments and other default text about classes and functions. The doc function displays this text to the user. You can disable inserting C++ comments or modify the text by editing the library definition file.

Automatically Use C++ Comments for Help Text

If these public constructs contain C++ comments, then MATLAB® appends the comments to the default MATLAB descriptions.

  • Functions and arguments

  • Member functions and arguments

  • Classes and structs

  • Data members

  • Enumerations and enumerants

  • Template functions and template methods of a class

MATLAB reads Doxygen style, C++ comments, but is not a Doxygen parser. For example, MATLAB processes Doxygen @brief and @details commands to add content to a class or function description. MATLAB reads @param and @return commands to augment argument descriptions. MATLAB uses the content of @code commands to provide code examples. Within any Doxygen command, MATLAB ignores formatting tags. For example, a Doxygen parser displays word as shown in this tag <b>word</b> in bold font. MATLAB simply includes the text <b>word</b> in the help. MATLAB does not display html tags <code>, ​</​code>, ​<p>, ​</​p>,​ and <br>.

By default, MATLAB copies C++ comments from library header and source files into the Description and, if available, DetailedDescription arguments for these methods. Enumerations optionally have EnumerantDescriptions arguments. You can review and edit the content by using the library definition file.

The Description, DetailedDescription, and EnumerantDescriptions arguments take string values. You can manually update the text in these values. For example, there might be more content in the .hpp file than MATLAB includes by default. Or you might want to include code examples for your use case.

If you do not want to copy C++ comments from the header and source files, then call clibgen.generateLibraryDefinition with the GenerateDocumentationFromHeaderFiles argument set to false. You can still enter text in the Description argument in the definition file.

Manually Update Help Text

This example uses the interface built in Header-Only HPP File. For another examples, see Modify Library Help.

If you created the interface, move to the folder with the defineschool.m file and school folder with the interface library. Alternatively, create the interface:

copyfile(fullfile(matlabroot,"extern","examples","cpp_interface","school.hpp"),".","f")
clibgen.generateLibraryDefinition("school.hpp")
build(defineschool)
addpath("school")
summary(defineschool)

The default help text for class Person is Representation of C++ class Person. To display the help, type:

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

To modify this text, edit defineschool.m. Search for the text Representation of C++ class Person.

Modify the "Description" value. Change:

"clib.school.Person    Representation of C++ class Person."

to:

"clib.school.Person    Class defined by name and age."

Save the file.

To rebuild the library, restart MATLAB. Navigate to the folder containing defineschool.m. Delete the existing interface file.

delete school\*.dll

Build the interface and update the path.

build(defineschool)
addpath school

Display the updated help.

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

Compare Generated Help With Header File Comments

The example described in Modify Library Help shows generated help for the XMLPlatformUtils.Initialize method in the Apache® Xerces-C++ XML parser library. This content comes from the Apache Xerces project, https://xerces.apache.org, and is licensed under the Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0.

MATLAB uses C++ comments in the PlatformUtils.hpp file.

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

After building the interface in the example, display the MATLAB help for the Initialize method.

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

See Also

|

Topics