Modify Library Help

R2026b

This example shows how to modify help generated for a MATLAB^® interface to a C++ library.

This example shows 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.

To build a MATLAB interface to this library, you need the header files and compiled library files. This example describes the build process and shows the output of building such a library. You cannot execute the code shown in the example unless you have access to the Xerces files.

Set Up

For information about setting up your environment, see Requirements for Building a MATLAB Interface to C/C++ Libraries.

Verify your compiler. This example assumes the library file was built with the Microsoft^® Visual C++^® 2017 compiler.
```
mex -setup cpp
```
Identify the path myPath to your .hpp and compiled library files. This example uses the library file xerces-c_3.lib.
```
includePath = "myPath\include";
libFile = "myPath\lib\xerces-c_3.lib";
```
Identify the header files required for your interface. This example uses the XMLPlatformUtils.Initialize method from the PlatformUtils.hpp file.
```
headers = includePath+"\xercesc\util\PlatformUtils.hpp";
```

Define MATLAB Interface

For information about defining the interface, see Define MATLAB Interface for C/C++ Library.

Generate the library definition file defineMyXercesLibrary.m.

clibgen.generateLibraryDefinition(headers, ... 
    "IncludePath",includePath, ... 
    'Libraries',libFile, ... 
    "Verbose",true, ... 
    "InterfaceName","MyXercesLibrary")

Edit the defineMyXercesLibrary.m file. This example resolves undefined functionality for the Initialize method only. Search for:
```
C++ Signature: static void xercesc_3_1::XMLPlatformUtils::Initialize
```

Update the defineArgument statements for locale and nlsHome to be null-terminated strings by replacing <MLTYPE> with "string" and <SHAPE> with "nullTerminated". For information about updating the code, see Define Missing Size Property.

defineArgument(InitializeDefinition, "locale", "string", "input", "nullTerminated", ...
    "Description", "locale The locale to use for messages."); % '<MLTYPE>' can be clib.array.xerces.Char,int8,string, or char 
defineArgument(InitializeDefinition, "nlsHome", "string", "input", "nullTerminated", ...
    "Description", "nlsHome User specified location where MsgLoader retrieves error message files." + newline + ...

In the same method, define the panicHandler and memoryManager arguments as scalar by replacing <SHAPE> with 1.

defineArgument(InitializeDefinition, "panicHandler", ...
    "clib.MyXercesLibrary.xercesc_3_1.PanicHandler", "input", 1, ...
    "Description", "panicHandler Application's panic handler, application owns this handler." + newline + ...
defineArgument(InitializeDefinition, "memoryManager", ...
    "clib.MyXercesLibrary.xercesc_3_1.MemoryManager", "input", 1, ...
    "Description", "memoryManager Plugged-in memory manager which is owned by the" + newline + ...

Validate the library definition file and resolve any errors.
```
libDef = defineMyXercesLibrary
```

Update Generated Help Text

Review the auto-generated help text.

className = "xercesc_3_1::XMLPlatformUtils";
methodName = "Initialize";
for i = 1:numel(libDef.Classes)
    if (matches(libDef.Classes(i).CPPName,className))
        classID = i;
        for j = 1:numel(libDef.Classes(i).Methods)             
             if (startsWith(libDef.Classes(i).Methods(j).MATLABSignature,methodName))
                methodID = j;
             end
        end
    end
end
Description = libDef.Classes(classID).Methods(methodID).Description                 
DetailedDescription = libDef.Classes(classID).Methods(methodID).DetailedDescription

Description = 
    "clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize    Method of C++ class xercesc_3_1::XMLPlatformUtils.
     Perform per-process parser initialization"
DetailedDescription = 
    "This content is from the external library documentation.
     
     Initialization <b>must</b> be called first in any client code."

Modify the text This content is from the external library documentation to display information about the Apache Xerces project. Open the library definition file.
```
edit defineMyXercesLibrary
```

Search for the xercesc_3_1::XMLPlatformUtils::Initialize method:

C++ Signature: static void xercesc_3_1::XMLPlatformUtils::Initialize

In the DetailedDescription argument, replace This content is from the external library documentation with the new content. The line now reads:

"DetailedDescription", "This content comes from the Apache Xerces project, https://xerces.apache.org, and is licensed under the " + newline + ...
"Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0." + newline + ...

Save the file.

Review the updated help text.

libDef = defineMyXercesLibrary;
libDef.Classes(classID).Methods(methodID).DetailedDescription

ans = 
    "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.
     
     Initialization <b>must</b> be called first in any client code."

Build Library and Display Help

```
build(defineMyXercesLibrary)
```
Add the library to your path. Either click the link in the message or type:
```
addpath(MyXercesLibrary)
```

Update the system path, identifying the location myPath of your library file.

dllPath = "myPath\lib"; 
syspath = getenv("PATH"); 
setenv("PATH",dllPath+";"+syspath)

Review the contents.
```
summary(defineMyXercesLibrary)
```

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

Modify Library Help

Set Up

Define MATLAB Interface

Update Generated Help Text

Build Library and Display Help

See Also

Topics