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.
Hilarious. LOL
[Via: Todd Berman]
Although these are numbered, they are in no particular order.
- You wake up in November hating the entire world.
- You always wanted to move to Canada, and the draft could be just the impetus you needed.
- You determine the leader of America based on how good they look in a fireman's hat.
- You need to know just how long his administration can go before it turns Powell into it's latest scapegoat.
- You want to see just how high this deficit can get before someone in the White House admits we have a problem.
- You can't get enough of that wacky National Security Advisor's latest hijinks.
- You live in Florida, because you figure if your vote isn't going to count, you might as well vote for the predetermined winner.
- Your hope that maybe if he wins this time, his father will jump out of the plane without a parachute this time.
- Another four years of neo-conservatives can't be worse than the first four.
- You think future presidents doing cocaine at Camp David is totally a good idea, and want to make sure Bush's daughters get more chances to prove how 'presidential' they can be.
- For some reason, the youth of America has always bothered you, and you would like to see more of their innocent lives lost in a pointless conflict.
- After 4 years of wonderfully funny flash animations, you have no idea how you can spend 8 hours at work without humour at George Bush's expense.
- He may have caused most of the rest of the world to lose what little respect it still had for America, but at least he didn't sleep with his intern.
- If George Bush is good enough for Jesus, he is good enough for you.
- You live in Tennessee, just got your thumbs, are relatively unsure how to use them, and missed the button to vote Yes on Prop 742 - Alien Sterility/Dentistry Program (Homage to the late master of comedy).
- Baby killing is good. Jodie Foster told you so.
- Pat Buchanan isn't running and you want the next best thing. Helms/Buchanan in 08!
- You are scared shitless.
- You are unable to resist the temptation to vote for Dick/Bush...
- Dick Cheney promised to show you his underground lair.
- Only thing better than one car wreck is two car wrecks.
- You were born mentally retarded.