Blog: Documentation

Cheat Sheet: Best practices for writing XML documentation in C#

March 11, 2015, (updated on October 4, 2018), 4 comments, Software Development

The XML documentation tags of C# are described very well in the MSDN. However, the article does not explain how the contained phrases and sentences should be written. This article tries to fill this gap by providing rules and some sample phrases. I recommend using StyleCop because its rules enforce some of the XML documentation recommendations from this article. Also check out the Visual Studio extension GhostDoc which automates and simplifies the writing of XML documentation. General All XML documentation phrases should end with a period (.) and no blank: <summary>Represents an XML document.</summary> public class XDocument { The summary […] Read more...

Tags: , , , , , ,

Write detailed C# XML documentation and still keep the source code clean

October 20, 2014, (updated on January 12, 2015), Software Development

For my open-source project MyToolkit I write a lot of documentation. Currently the documentation for a class has to be updated in two locations: The source code and the project’s wiki. I asked myself how to avoid this and document everything in the source code file – while keeping the source code simple by not putting too much documentation in it. To write detailed documentation in your C# code, you can use the tags <remarks> and <example> (<summary> should always be there). To avoid polluting the source code file with documentation, you can additionally use the <include> tag to “outsource” […] Read more...

Tags: , , ,

  Page 1 of 1