Rick Strahl summarizes my discussion with him on XmlDocs in source vs repository.
I wanted to clarify few things about how we (at DataDynamics) develop and document our components.
We typically have a team of 2-3 developers working on different parts of the project.
Developers are not necessarily in the same location and they would not be connected to our network all the time, they check out the code they're working on and code away whether they are at the office, at home or traveling. They connect back to the network to check in their code (and documentation) into StarTeam.
Developers are required to document the headers of public types and members using xml documentation standards introduced by the C# compiler. The C# compiler generates warnings in our release build if we're missing any documentation. And it generates the XML files required for intellisense in VS.NET.
The XMLDocs compiler checks are great, however, the format and location of the comments are a mess. The documentation written by developers has to be edited by our documentation personnel. They do not have -and shouldn't have- access to our source code repository.
XMLDocs has a special tag that allows storing the comments in a separate file. <include>. The format of the file is open and it can be any xml that produces valid content from an XPath expression. We chose to create an .xmldoc file for each source file. Each node the xmldoc file would represent a type or a member in our source code file. Think of it like pairing the cs/resx in the case of winforms.
Rick's example is different from how we write our files, we do not keep a node for the project because some of our files can be used in multiple projects. Also, we do not have a node for the namespace either. Each node has a unique id that is "namespace.type.member" if the member is overloaded we simply add a #1..n at the end. The xpath would be
'@name="namespace.type.member#1..n"
Keeping the xml content in separate files allows us to work with it just like we do with the code, write it in a distributed independent fashion, version it, and control access to the source code repository.
Once our developers have completed their part of code/doc, our documentation persons edit the documenation before we generate the assemblies/intellisense xml. We use the same xml to generate the library reference help and integrate those topics with our user guides to create the final MSHelp 2.0 files and PDF manuals. We are currently using DocumentX and HelpStudio from InnovaSys for this final step.
What I described here is very similar to how Microsoft documents the framework. You can see the <include> tags in the Rotor source code.
All this works great, however, editing XML non-WYSIWYG in a separate file (without a schema) is error-prone and can be made a lot easier if there was a simple add-in that popups a dialog to edit the comment and place it in the proper associated file and place the <include> tag in the source code.
wwHelp and DocumentX both have nice add-ins to edit the comments but they miss the piece of how important keeping the source separate from docs is and the need to keep the xml comments sync'ed to the code to make use of the compiler generated warnings.
They are both great products and we do use them on different projects to write our user guide and how-to topics and for final integration of the xmldoc with the user guide to create the final mshelp files.
Rick (of wwHelp) and Richard (of Innovasys) try to fit the xml docs directly with their products. I think what they should do is two things:
Simple add-in like I described above to allow WYSIWYG editing the xmldoc and optionally inserting the comment or the include tag into the code. Various options can be made as part of the project properties, i.e. where to place the documentation (code vs include) and location of the include files.
The repository would come into play after the C# compiler has generated the XML intellisense file and it would simply import the file into the project.
Both products do #2 very well, so I am hoping they would introduce a good solution for #1.