In my previous post on how to find static fields in the entire solution using ReSharper and a free ReSharper plug-in, Agent Smith, I briefly mentioned that the described trick can be used to aid documenting the public API. Some people have asked me to elaborate, so here goes:
Typically, documented API should cover all public implementations, classes and interfaces. Visual Studio provides a mechanism called XML Comments, which allows you to decorate your classes, methods, fields and properties with XML, and later generate documentation from those comments. A free add-in for Visual Studio called GhostDoc can assist documenting the API - by pressing a shortcut key (default is Ctrl-Shift-D) on any part of the class (i.e. methods, properties, etc.) it will generate a stub XML comment.
For best results, default comments generated by GhostDog should almost always be replaced with a proper description.
Depending on your preferences, you may not want to document any internal implementation. For this example, we will find all public members (methods, fields, etc.), except in internal classes.
After installing Agent Smith plug-in and GhostDoc (and optionally disabling Agent Smith’s built-in naming conventions, which might conflict with those of ReSharper), go to ReSharper Options - C# - Formatting style - Agent Smith code style settings, and remove all existing rules:
Now press Add on the left hand side, and select Public under Visibility:
This will create a rule called Public Declaration, and will be applied to any member (method, property, field, etc.) having public visibility.
On the right hand side, under Except, press Add and add the following:
This will add the exception on internal classes.
The steps above will add a suggestion Public declaration should have XML comment. to all matching members across the solution. In order to find all of them, use either the Code Issues Inspector, or turn Agent Smith’s Members must have XML comment suggestion in Inspection Severity to Show as error, and navigate the errors using ReSharper shortcut keys. Both methods are further detailed in my previous post.
Press Ctrl-Shift-D (or whatever is bound to GhostDoc’s Document This command) on each matching member, and give a proper description, replacing the default generated comment. Please view the XML Documentation Comments guide on MSDN for best practices.
Happy documenting!