Published: Wednesday, 06 April 2016 16:02
When you write XML doc comments in your .NET code for your internal purposes, you usually don't care about their formal perfectness. All you need is to be clear and precise.
The situation is however different, when it comes to commenting an API that will be publicly available to the end-users. The documentation must be clear, formally correct and consistent.
I'm not going to talk about a grammar, English is not my strong point. But I will show you the most common mistakes and some simple rules that can make your documentation even better. The list is by no way complete. I collected it from my experiences with my own or my clients' APIs and from what I have observed in MSDN. The points are in random order. All improvements can be done manually without any tool, but where appropriate, I will show how they can be simplified with our VSdocman, especially with its WYSIWYG comment editor.