10

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?

7
  • 3
    There are plenty of libraries and packages that deal with XML documentaton.
    – Jodrell
    Commented Oct 1, 2012 at 9:49
  • 1
    Do you actually need to find such information by reflection? Why don't you combine the well known xml documentation, and some source code version control (svn is showing exactly what has been done)? In you case, what about if two developers changed the same method/class?
    – Steve B
    Commented Oct 1, 2012 at 9:50
  • This is not a good idea, IMO, as you don't typically need the documentation in runtime. XML documentation is already ugly enough as is, this approach would be even uglier. Try to imagine a more complex method where description consists of few paragraphs. Howe would that look with attributes? Commented Oct 1, 2012 at 9:52
  • I don't need to, it just seems neater. Not to mention it's prettier. The XML notation for comments in C# is sooo butt-ugly. So much worse than PHPDoc: goo.gl/1iZZJ. Why on earth wouldn't C# use /** */ syntax instead of that stupid ///? Also, XML is dead. Commented Oct 1, 2012 at 9:54
  • @ZdeslavVojkovic I agree XML is ugly. Do you think this is uglier? I'm not so sure. You could use @"" multiline strings. And C# programmers are already used to reading C# code (rather than XML). But maybe you could just use this method for Author and Parameters and not for description? And surely the run-time overhead is not great. It would be compile-time if anything... Commented Oct 1, 2012 at 9:59

3 Answers 3

5

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.

4
  • I'm still not sure formatting for long blocks of text is actually any worse. I agree with your point about keeping author information in version control, but that's about what to document rather than how - this method could still be useful for parameters. The other arguments are simply about current support, which is conceding to a very top-down structure of control in C#'s evolution, but I think you're right, this isn't a battle I'm likely to win. I'm just never gonna properly document my classes, 'cos it breaks my heart to create something so ugly. Oh well. Commented Oct 1, 2012 at 10:11
  • So then you should look for resolving the problem within you ;-) Proper documentation is a matter of discipline at the first place. Formatting is second. However, it's an uphill battle the get rid of XML comments. Maybe you could start with getting some helper add-on like ReSharper to make typing XML comments easier. Commented Oct 1, 2012 at 10:19
  • 1
    There IS an excellent use case for documentation in attributes: Runtime end-user documentation. For instance, when you have a large set of console commands, you can store the description of the commands in attributes and extract these description for MyApp --help.
    – Tomas
    Commented Dec 17, 2012 at 10:14
  • @Tomas Yes, I'm using this technique too. However, in your case it's application documentation, not source code documentation. Commented Dec 17, 2012 at 12:46
3

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?

0

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.