Modify Library Help

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 shared library files. This example describes the build process and shows the output of building such a library. You cannot, however, 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 Interface to C++ Libraries.

Verify your compiler. This example assumes the shared library file was built with the Microsoft^® Visual C++^® 2017 compiler.
```
mex -setup cpp
```
Identify the path myPath to your .hpp and shared 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++ Library.

Generate the library definition file defineMyXercesLibrary.mlx.

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

Edit the defineMyXercesLibrary.mlx 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 Information for MATLAB Signatures.

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 call:
```
addPath(MyXercesLibrary)
```

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

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

Review the contents of your interface.
```
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()

    No outputs

Documentation