Generating code documentation [closed]

Question

I want to generate code documentation in a simple format. The key items are Method Signature, members, constructors, methods. I am taking various applications in .NET and creating documentation for them. I will be adding notes to each item. The end result should look similar to MSDN or Java API documentation.

So, I want to take my source code and have some kind of template generated that I can append notes to. I want to pick and choose certain classes and not others across various applications.

I'm not talking about intellisense documentation. This documentation will be used for reference outside of visual studio. AFAIK, that's all the XML comments are good for in .NET.

I'm documenting various interfaces and entry points for writing extensions for a 3rd party application. We do not own their code, so I can't just go in and append XML comments to their interfaces, classes etc. Instead, I need to implement the interface and comment it up. Then document it on the web. Documentating each implementation just to explain their architecture is redundant. They do not document their stuff...that's the core issue here.

Is there any tool that can assist with this process? What do you suggest?

Answer 1

Doxygen is pretty great at translating XML to a human-readable format, such as MSDN-style HTML or HTML Help. (chm) It will work with both XML generated by Visual Studio, as well as XML you create on your own, or acquire from other sources.

Another option is Sandcastle and SCHFP, though that has seen less maintenance.

In both of these cases, you can extend the XML markup for more than just VS Intellisense, including commentary that is only to be used for external documentation, etc.

Answer 2

This is built into .Net by using the following syntax

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

and then use a codeplex project called SandCastle

Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments.

XML Comments on MSDN: http://msdn.microsoft.com/en-us/library/b2s063f7.aspx

SandCastle: http://sandcastle.codeplex.com/

Answer 3

I use NaturalDocs. The advantage (and I presume the name) stems from the fact that it infers formatting mostly from spacing, and not from tags. You don't have to decorate your comments with a lot of <method> and things like that, making the comments much more readable "in the wild".

A NaturalDocs comment would look something like:

/* Function:  my_method
 * 
 * Accepts a Turing machine and an infinite data tape, and determines
 * whether it will halt.
 *
 * Parameters:
 *   turing_id - The ID of a valid Turing machine.
 *   tape_ptr  - A pointer to the start of the inifite-length tape.
 *
 * Returns:
 *   If the machine halts, returns 0.  If the machine doesn't halt,
 *   return value is undefined.
 */
extern int my_method(turing_id_t turing_id, void *tape_ptr);

NaturalDocs would take that and generate an HTML file with an appropriate signature, description of the method, table-formatted list of parameters, and any additional sections (Returns here). It will also generate a table of contents defaulting to organizing by file. You can also group things by types other than Function (such as Types, Macros, and so forth).

I may sound overenthusiastic, but when we changed to NaturalDocs it knocked a huge amount of boilerplate out of our headers and made them look much more ... (cough) ... natural.