Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  
What's a problem with JavaDoc then? –  SK-logic Feb 27 '12 at 15:59
4  
Code documentation for what language? –  Oded Feb 27 '12 at 15:59
    
What have you searched for? Why did it not meet your requirements? –  Bernard Feb 27 '12 at 15:59
4  
And what's the issue with the .NET XML documentation? –  Oded Feb 27 '12 at 16:01
3  
Extracting the comments in built into Visual Studio - in the project properties under the Build tab there is an Output section where you can check a checkbox for XML documentation file and specify an output path. You can then do what @SK-logic suggests. –  Oded Feb 27 '12 at 16:16
show 4 more comments

3 Answers

up vote 5 down vote accepted

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.

share|improve this answer
    
I've used doxygen in the past and been happy with it, sandcastle works too although I'd probably lean towards doxygen having used it more often. –  Trevor Pilley Feb 27 '12 at 23:02
add comment

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/

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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