As we're preparing to release the open API for developing OmniaMea plugins, I'm currently investigating various solutions for generating the API documentation. I've long resisted the idea of writing documentation as the XML doc comments (prefixed with ///), because the comments clutter the code pretty heavily - much more than JavaDoc comments (if you don't use too many HTML tags in your JavaDocs). However, the comment editing experience provided by Visual Studio (type three slashes and get a full template for the comment block) is hard to beat, and I couldn't talk Resharper developers into providing a similar solution for JavaDoc comments (even though they're equally supported in Visual Studio 2003). Thus, I gave in and decided to do it the standard way.
Now I'm looking for a tool to generate the final documentation file. NDoc deals with the generation part pretty well, but I'd like to include a set of manually written pages (Developer's Guide), and it looks like all that NDoc offers for that is a list of files to include separated with semicolons... which is not quite user-friendly.
I've tried using Document X, but aside from general slowness (10-15 seconds to open an empty contents file for editing is a bit too much for my taste), it is simply buggy. I could live with being suggested to edit the return value description for functions returning "void", but ignoring "ref" modifiers on function parameters makes Document X totally unusable. The API signatures in the help file must be correct, period.
Another problem is generating documentation for an XML file format. Our OpenAPI allows to define actions, resource icons and some other information declaratively in an XML file, and I'd like to be able to easily generate documentation for the XML format. I've found several tools for documenting XML schemas (Document X does that too), but they don't seem to do the right thing. They do a pretty (sometimes very pretty) printing of the XSD definition, and that must be great for those who want to understand how the XSD is set up - but not for those who want to quickly create an XML document matching the schema. Microsoft does a great job with their schema documentation - concise and to the point - but, as far as I know, they never released a tool that would allow me to generate such documentation. Is it time to try hacking NDoc to add this functionality?..
As usual, pointers to tools that could help me solve the problems are very much welcome.
Posted by Dmitry Jemerov at May 7, 2004 12:50 AMTake a look at Doc-O-Matic Professional. I use it for Delphi, and you can add pages where you want.
Posted by: Tom Clay at June 2, 2004 09:39 PMI'd be interested in what you discover. doxygen was looking favorite in my investigations.
Posted by: Paul Andrews at July 3, 2004 06:45 PMI have the same problems and I found Document! X too.. Yes, it is buggy and that ref thing sounds awful. So the good question is, who will save us?
I was thinking of a CodeRush plug-in but I'm a huge fan of ReSharper and would never want to switch. Now that 1.5 EAP is out, even more less.
Posted by: RGabo at February 11, 2005 02:44 PMWow, now I see this is an almost a year old post.
Did you try Docuemnt! X 4? They might have fixed these problems.. I will be using it for the next couple of days and I will be more than happy to blog and link about my experience.
Posted by: Gabor Ratky at February 11, 2005 02:45 PM