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.
It is also possible to manually edit the C# source files to include documentation comments or to add additional formatting tags to create the desired output. Keep in mind, though, that any changes you make to the .cs files will be lost if you regenerate the C# classes. See To manually add XML documentation comments below for instructions.
To manually add XML documentation comments
| 1. | After generating C# classes, open the class file(s) and find the “To Do” comments. There is a “***To Do*** Add method description” comment before every user-defined method for which there was no description text found in the SMC. There is a “***Field To Do***” comment before every property or field in the structure classes for which there was no description in the repository. |
| 2. | Replace the “To Do” lines with descriptions of the methods and fields. Add comments for the <param> and <returns> tags if desired. |
| 3. | Save the file(s). |
Generating an XML file
Select the “Generate API doc” option in Workbench or use the gencs -a option on the command line to indicate that you want to generate an XML file when you build the assembly.
When you build the assembly, a file named assembly_nameAPI.xml will be generated and placed in the same directory as the assembly.
|
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 do indicate in Workbench or with the command line 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.
|
|
Microsoft originally developed Sandcastle and downloads can still be found on the Microsoft website, but they are not the most recent. We recommend you go to the GitHub site instead for information about the product and to download the latest version. |
