How can you define and maintain XML code comments outside of the main solution?

Question

I am building a public API and recognize the value of complete API documentation on public methods. I know it's easy to keep them in directly in code files as XML annotations on classes, methods, properties, etc.

But I hate cluttering clean source code with public comments. What's the best way to create, and maintain XML code documentation somewhere other than in the code files, and still produce builds in Visual Studio that emit the .xml to the appropriate location (\bin\ folder, etc.)?

Answer 1

Sounds like a really nice way to keep your documentation out of sync with your code. Why not just use the outlining/folding features of visual studio to have it all collapsed when working with the code ?

Answer 2

I would personally stick with the comments in the code. You could always put regions around them and collapse them if you have to. By keeping them directly with the code, you get the benefits of Intellisense filling in parameter names, etc. I know it can be a bit of a distraction, but I find it the best way to go. It also means that when reading the code you can check what you've documented it to do very easily.

An alternative might be to keep the comments in a separate file (per source file) and have a pre-build step which merged the files together in some temporary area, which is where you'd build from. Your XML comments would need to have some identifier before them to make it clear which member they described, and you'd need to write the tool to do the merging. You could make this simpler by including a single comment before each method, e.g.

// doccomment:MyMethod(asd)

The bit after doccomment would be irrelevant, just used as a token, but I'm sure you could come up with your own convention to keep it in sync with the other file, which would look like this:

// doccomment:MyMethod(asd)
/// <summary>
/// This method squurbles the frobdicator.
/// </summary>

You'd then just replace the single line comment with the identified text in the comment file.

This does all sound like a real burden though - I would think long and hard about how painful having the comments in the code really is.

Answer 3

The next best thing could be to fold them in the editor so that you only see

/// <summary> ...

There are a number of macros that can do that for you.

Answer 4

In code /// comments are good (brilliant idea), but they can get unwieldy pretty quickly, and they're only a small part of proper documentation. How about a combined approach where the /// gives the basic comment, and then use The Sandobox Builder to add in further detail for the public interface.

I'd agree with krosenvold if only the outlining/folding wasn't so contrary at times - really does anyone know how VS decides what to open/close.

Answer 5

When ever you have two (or more) files with correlating information one (or more) will be out of sync.

I believe this is an extension of Murphy's Law.

That said... The accepted way to reference portions of an XML file is with ID attributes or XPath. Good luck.