C# – API documentation for self-built SDK

C# – API documentation for self-built SDK

What should you pay attention to when creating a .NET library yourself? I would like to share with you some tips on building your own library.

In the construction of API documentation for this introductory issue, self-built SDKs must not ignore its API documentation. This will determine whether your SDK is robust and friendly.

Add API documentation in code

When users use class libraries, they usually need to view the annotations of the API through VS’s Intellisense or F12 decompilation, and use these annotations to understand how to use the API. In C# source files, you can document the API required by a class library in your code by writing special comment fields represented by triple slashes. The comment field contains XML elements that describe the code block below it. XML elements provide a structured format for the API document and are easy to parse by tools such as compilers. For example:

/// 

 /// Function does an important thing.
 /// 
 /// The result.
 public string DoSomething {}
 

Generate API document XML file

The

GenerateDocumentationFile property controls whether the compiler generates an XML documentation file for the library. By setting this property to true, the compiler will find all annotation fields in the source code that contain XML tags and create an XML document file based on those annotations. The generated XML file is placed in the same output directory as the assembly and has the same file name (but with an .xml extension).

When this option is enabled, the compiler will generate a CS1591 warning for all members in the project that are declared publicly visible but do not have XML documentation comments.

   true
 
 

Class library is set as a reference assembly

Compared with implementation assemblies, setting the class library as a reference assembly allows you to expose only the members declared as publicly visible and hide the private implementation.

For example, class libraries defined by data structures and interface protocols do not have specific assemblies that need to be loaded and executed, so this setting is suitable.

Publish class library

Published together with the XML document file and the DLL, both of which must be in the same directory.

API documentation comments are visible when referencing a DLL. For example:

//
 // Summary:
 // Function does an important thing.
 //
 //Return results:
 //The result.
 public string DoSomething {}
 

References

• C# Guide – XML ​​Documentation Comments
• Reference assembly