Generating API documentation

You can create API documentation for the developers who use your Synergy assembly. To do this, you will need to do the following:

1.

Add documentation comments for your methods, return values, and parameters.

2.

Generate an XML file when you build the assembly.

3.

Use a third-party application to create documentation from the XML file.

Adding documentation comments

To produce useful documentation, you must provide a description for each of your user-defined methods. (We include documentation comments for the xfNetLink .NET utility methods in every class.)

• If you are attributing your code and using the XML file output by dbl2xml to populate the SMC, use the documented syntax to include comment text for methods, return values, and parameters in the Synergy source file. See Documentation comments.
• If you are using the MDU to populate the SMC, enter comment text in the description fields in the MDU as you define methods. The MDU includes fields for method description, return value description, and parameter description. See Creating new methods and Defining parameters for instructions on entering data in these fields.

When you generate C# classes, the descriptions in the SMC are included in the generated files as XML documentation comments. If a method does not have a method description in the SMC, a “To Do” comment is inserted in the generated file. If a return value description is not provided in the SMC, no text is inserted in the file for the associated XML tag. If a parameter description is not provided in the SMC, the parameter name is used as the comment text.

For structures passed as parameters, the field description in the repository is included as the XML documentation comment for the property (or field) in the generated class file. If a field does not have a description in the repository, the comment “***Field To Do***” is inserted in the generated file.

While is is possible to manually edit the C# source files to include documentation comments or to add additional formatting tags to create the desired output, we do not recommend this. Any changes you make to the .cs files will be lost if you regenerate the C# classes.

Generating an XML file

Indicate that you want to generate an XML file:

• In Workbench, select the “Generate API doc” option in the Component Information dialog.
• If you are building from the batch file, use the gencs -a option.
• If you are building with MSBuild, select the “XML documentation file” option in Visual Studio’s Project Properties dialog. (This option is named slightly differently in different versions of Visual Studio.)

When you build the assembly, a file named assembly_nameAPI.xml will be generated and placed in the same directory as the assembly, or, if you’re using MSBuild, in the directory you specify in the dialog.

When the C# classes are generated, the XML tags necessary to produce documentation (e.g., <summary>) are included in the source files regardless of whether you have indicated that you want to generate API documentation. If you indicate in Workbench or with the gencs -a option that you want to generate API documentation, a command to create the XML file is added to the batch file.

Creating the API documentation

A third-party product, Sandcastle, is required to create the API documentation using the XML file (assembly_nameAPI.xml) produced when you built your assembly. Sandcastle can be downloaded from github.com/EWSoftware/SHFB.