Question

In the MSDN Attributes Tutorial they use Author as an example for an attribute:

[Author("Jane Programmer", Version = 2), IsTested()]
class Order
{
    // add stuff here ...
}

This seemed to me to be a good idea because it would allow you to use reflection to group classes by author (for example) – effectively exposing metadata that would normally be in documentation to the compiler, which could be useful. I immediately thought “aha! I should be using attributes for all my inline block documentation” – e.g.:

[Author("Me")]
[Description("Add 1 to value")]
[Param("value", "The original value to add 1 to")]
public int AddOne(value) {return value + 1;}

However none of the answers I could find about documentation and attributes seem to suggest this method. They all use XML for inline documentation.

Are there any built-in attributes to assist with inline documentation? If not, are there any libraries / packages out there that include pre-defined sets of attributes for inline documentation?

Answer 1

Some disadvantages of keeping documentation in attributes:

• poor formatting for long texts;
• no support by Visual Studio add-ons (e.g. using ReSharper’s documentation preview feature);
• no support by 3rd party documentation generation tools;
• inclusion of documentation in assemblies which significantly eases reverse engineering;
• duplication of metadata in source codes with metadata stored in a version control system (there’s no point in tracking any declaration’s author and version in the source code, when the VCS gives you much more precise information — VCS’s don’t lie).

I can’t think of any advantage right now. In case I would really need it, it’s always possible to parse the XML documentation comments and transform the whole codebase into any attributed form.