Ayende @ Rahien

Hi!
My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:

ayende@ayende.com

+972 52-548-6969

, @ Q c

Posts: 18 | Comments: 82

filter by tags archive

Generating API Documentation

time to read 3 min | 419 words

I want to generate API documentation for Raven DB. I decided to take the plunge and generate XML documentation, and to ensure that I’ll be good, I marked the “Warnings as Errors” checkbox.

864 compiler errors later (I spiked this with a single project), I had a compiling build and a pretty good initial XML documentation. The next step was to decide how to go from simple XML documentation to a human readable documentation.

Almost by default, I checked Sandcastle, unfortunately, I couldn’t figure out how to get this working at all. Sandcastle Help File Builder seems the way to go, though. And using that GUI, I had a working project in a minute or two. There are a lot of options, but I just went with the default ones and hit build. While it was building, I had the following thoughts:

  • I didn’t like that it required installation.
  • I didn’t know whatever you can easily put it in a build script.

The problem was that generating the documentation (a CHM) took over three and a half minutes.

I then tried Docu. It didn’t work, saying that my assembly was in the wrong format. Took me a while to figure out exactly why, but eventually it dawned on me that Raven is a 4.0 project, while Docu is a 3.5. I tried recompiling it for 4.0, but it gave me an error there as well, something about duplicate mscorlib, at which point I decided to drop it. That was also because I didn’t really like the format of the API it generated, but that is beside the point.

I then tried doxygen, which I have used in the past. The problem here is the sheer number of options you have. Luckily, it is very simple to setup using Doxywizard, and the generated documentation looks pretty nice as well. It also take a while, but significantly faster than Sandcastle.

Next on the list was MonoDoc, where I could generate the initial set of XML files, but was unable to run the actual mono doc browser. I am not quite sure why that happened, but it kept complaining that the result was too large.

I also checked VSDocman, which is pretty nice.

All in all, I think that I’ll go with doxygen, it being the simplest by far and generating (OOTB) HTML format that I really like.


Comments

commenter

" it gave me an error there as well, something about duplicate mscorlib,"

Could be you need to bump up the tools version in the csproj.

2.0 tools don't know how to build 4.0 projects so they always pull in the old mscorlib.

bjjonker

"I didn’t know whatever you can easily put it in a build script."

The saved file output from the Sandcastle Help File Builder is an MSBuild-based project file, so it should integrate well with a build script.

Matt Salmon

Hi Ayende

With Sandcastle, you can speed up the build substantially doing the following:

Click on the "ComponentConfigurations" properties button, and add "Cached Framework Comments Index Data", "Cached MSDN URL References", and "Cached Reflection Index Data".

HTH,

Matt

Christopher Bennage

What?! No Rhino.Doc?

(Sorry, I know the joke is getting old.)

We settled on Doxygen for Caliburn (though I believe that was two years ago).

Frans Bouma

You didn't try Document! X?

It's commercial, true, but gives the least # of friction (although VSDocMan also looks nice) as in: you don't have to spent extra time when writing code.

Paul Hatcher

Another vote for Document X - the other nice thing is that you can put topics other than straight API stuff

Dave Barone

This is something that's puzzled me for a while - Why .NET does not have a standard document generator. Ruby has RDoc. I too tried Sandcastle a couple of years ago but gave up as well. It's not a product but a set of (very raw) tools - it's just too much hard work to use. Doxygen on the other hand is good, but is not .NET specific, and does not seem to cope with all edge cases in .NET. Maybe the thought of building Rhino.Doc isn't such a bad idea ???

Ayende Rahien

Matt,

Thanks, that took over 2 minutes from the help build time

Toni

About a year ago I was using DocProject, http://docproject.codeplex.com/. It installs VS template which you can use to create the project and integrates into msbuld quite nicely.

Comment preview

Comments have been closed on this topic.

FUTURE POSTS

  1. The insidious cost of allocations - 12 hours from now
  2. Buffer allocation strategies: A possible solution - 3 days from now
  3. Buffer allocation strategies: Explaining the solution - 4 days from now
  4. Buffer allocation strategies: Bad usage patterns - 5 days from now
  5. The useless text book algorithms - 6 days from now

And 1 more posts are pending...

There are posts all the way to Sep 11, 2015

RECENT SERIES

  1. Find the bug (5):
    20 Apr 2011 - Why do I get a Null Reference Exception?
  2. Production postmortem (10):
    03 Sep 2015 - The industry at large
  3. What is new in RavenDB 3.5 (7):
    12 Aug 2015 - Monitoring support
  4. Career planning (6):
    24 Jul 2015 - The immortal choices aren't
View all series

Syndication

Main feed Feed Stats
Comments feed   Comments Feed Stats