Using Attributes for Documentation in C# [closed]

问题

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?

回答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.

回答2:

The question here seems to be 'what is documentation?'. If the 'stuff' your interested in needs to be accessible by reflection then your implied solution of attributes is a solution. But if the intent is to use standard documentation tools to build documentation then not so.

The need here begs the solution. What is the need for the 'documentation'. Perhaps the wrong question?

回答3:

Just to mention it for the sake of completeness, in the Testing Projects you could do:

[TestProperty(“Author”, “Ducky”)] 
public void SomeTest()
{
       ...
}

You could extend that approach for regular code. I rather not comment on theoretical issues. That said, perhaps script that uses repository to extract all the "authors"/"editors" of the specific file/class/method can be created.

来源：https://stackoverflow.com/questions/12670879/using-attributes-for-documentation-in-c-sharp

标签

.net

attributes

documentation