custom documentation for C# code

Question

Is there a customizable documentation generator for C#? As opposed to native xml documentation which provides documentations for classes, methods, properties, the documentation I am referring to here is more lower-level, ie it documents the flow of a method.

for example in the given code

void SomeMethod(){

///doc:Do X
SomeCodeToDoX

///doc:Do Y
SomeCodeToDoY

///not tagged
SomeCode

}

The documentation will capture doc:Do X and doc:Do Y, and will document Do X and Do Y as the flow inside the method SomeMethod

*I hope I made the question clear enough.. if I didn't please comment to ask clarification

Answer 1

Don't know if this answers your question, but you can use SandCastle: http://sandcastle.codeplex.com/

It creates MSDN documentation by reflecting assemblies. You can (but not required) add your own documentation tags too.

Answer 2

You can use whatever XML elements you like within doc comments, as far as I'm aware - but they have to be attached to a member; you can't just add doc comments to bits of code within a method, I'm afraid.

Or at least, you can, but it won't get picked up as part of the generated XML file and you'll get a warning like this:

Test.cs(11,9): warning CS1587: XML comment is not placed on a valid language element

It's possible that if you disable that warning and use Doxygen to process the source code instead of the built in generator, you might be able to get something going... but you should be aware that it will be very specific to your environment. I suspect that the benefits wouldn't be worth the pain, myself. I'd also give a warning about the readability of code which has a large amount of comments in - it can get very distracting when you really just want to see the code itself.

(For some reason SO is barfing when I try to post a link to Doxygen... will file a bug on Meta.)