English is not my mother tongue, this page may contain incorrect words or sentences.

urriellu.net => Articles => Software => Documentation in C#

When coding in C# you can write one-line comments beginning by "//" or multiline comments between "/*" and "*/". There is no need for adding an asterisk at the beginning of each line but Visual Studio does it automatically and it is more clean.

cvl-en.cs, 6 lines      [download]

  1. //comment
  2. int a = 1; //another comment
  3. /* multi-
  4. * line
  5. * comment */
  6. int b = a;
  7.  

But what is really interesting is the ability to add documentation directly into the source code. You can write well-structured XML comments and they will help you when autocompleting names of classes, objects, variables or anything else, and you can build the documentation for developers (which explains the code) automatically using those comments.

Note: all these labels are optional. They are just a few of them.

Documentating classes

cls-en.cs, 11 lines      [download]

  1. ///<summary>
  2. /// Main Class
  3. ///</summary>
  4. ///<remarks>
  5. /// Reads config files and creates threads that executes the rest of the app
  6. ///</remarks>
  7. class CApp {
  8.     static void Main(string[] args) {
  9.         ...
  10.     }
  11. }
  12.  

Between <summary> and </summary> you can add a summary or description of the class. Labels <remarks> and </remarks> are used for special comments about the class, they won't be shown when autocompleting but they will appear on the documentation.

Documentating members

miem-en.cs, 10 lines      [download]

  1. class CApp2 {
  2.     ///<summary>
  3.     ///Amount of retries when accessing a file
  4.     ///</summary>
  5.     ///<remarks>
  6.     ///It can be modified at any time
  7.     ///</remarks>
  8.     int var = 1;
  9.     ...
  10. }
  11.  

The same as classes.

Documentating methods/functions

met-en.cs, 14 lines      [download]

  1. ///<summary>
  2. ///Reads config files
  3. ///</summary>
  4. ///<return>
  5. ///true if the config file was successfully read. false in case of error
  6. ///</return>
  7. ///<param name="file">
  8. ///Path to the file that contains the configuration parameters
  9. ///</param>
  10. public bool ReadConfig(string file) {
  11.     bool c = false;
  12.     ...
  13.     return c;
  14. }
  15.  

Between <return> and </return> the value returned by the function is explained, and <param> labels are used for describing each one of the parameters sent to the function.

Generating documentation

Documentation files can be also generated. On Windows using .NET Framework implementation by Microsoft you can do:

C:\>csc /doc:Documentation.xml Program.cs

On Unix-like systems running Mono:

mcs -doc:Documentation.xml Program.cs

And on Windows running Mono:

C:\>mcs /doc:Documentation.xml Program.cs

Automatic documentation

There is an add-in for MS Visual Studio 2003 and 2005, GhostDoc, which allows you to add documentation comments using a simple keyboard shortcut for any kind of member you are documentating (a class, method, variable...).