Publish Help Text for MATLAB Interface to C/C++ Library

R2026b

When you define a MATLAB® interface, during interface generation, MATLAB inserts C++ header file comments and other default text about classes and functions. The doc function displays this text to the user. To disable inserting C++ comments or modify the text, use the Description, DetailedDescription, and EnumerantDescriptions properties. These properties enable you to customize help text programmatically as part of your interface definition workflow.

You can modify this help text when customizing the interface definition using clibgen.api objects.

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. In 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 properties for these methods. Enumerations optionally have EnumerantDescriptions properties. You can review and edit the content by using the clibgen.api.InterfaceDefinition object.

The Description, DetailedDescription, and EnumerantDescriptions properties take string values. You can update the text by modifying these properties. 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, set the GenerateDocumentationFromHeaderFiles property to false on the InterfaceConfiguration object before creating the InterfaceDefinition.

icfg.GenerateDocumentationFromHeaderFiles = false;

You can still enter text in the Description property in the InterfaceDefinition object.

Update Help Text

This example uses the interface built in Publish MATLAB Interface Using Live Script Workflow. Move to the folder with the defineschool.m file and the school folder containing the interface library.

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, update the interface definition, for example in 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.

After updating the interface definition, rebuild the interface to apply the changes. 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

Live Editor Tasks

Topics