2010
04.09

libtcod 1.5.1 doc system

Ok I think it’s time to unveil the doc generator that will be used in libtcod 1.5.1.

The main issue with libtcod has always been that as far as I know, no existing generator can generate doc for several different languages from the same javadoc-like source.

Well, such a generator now exists 🙂 It’s called doctcod (smart, eh? :D). With it, maintaining libtcod’s documentation will be all silky compared to what it is currently. It also uses Mingos’ new skin so not only it’s better for doc maintainers, but it’s also better for doc readers 🙂

It’s based on javadoc-like comments in the .hpp headers of libtcod. Adding support for a new languages can probably be done in a matter of days (including updating the whole documentation). Just saying that in case some Lua wrapper pops up one day 😉

I kept the best part for the end : since the generator swallow all the headers at once before spitting out the html doc, it will be very easy to generate a per-language reference of all functions… It almost sounds like Christmas, I think I can hear the bells…

7 comments so far

Add Your Comment
  1. Bells shmells, but I was the one who had to update the CSS and the language icons (to include C#@)… Anyawys, GREAT JOB :;z\D

    (sorry for typos, if they’rep present,, but I’m completeyl drunk tonight)

  2. Hehehe, i felt your css skills were getting rusty, so i found a way for you to practice 😛

  3. Awesome! Both the custom-tailored doc generator and the graphic style 🙂

    Hm, looking at Javadoc, I can’t help but miss Wikipedia’s lean syntax style. You’ll notice it ditches keywords and relies almost exclusively on punctuation! For instance, instead of @param [parameter] [description], you could have something like [parameter]: [description]. But unfortunately no doc system does that 🙂 Anyway, one great advantage of doctcod (hey you can read it backwards!) is that many folks are already familiar with Javadoc’s system, that’s a pretty big selling point IMO 😉

  4. BTW when I said “Javadoc” I was actually thinking “Doxygen” since it seems like the most popular doc generator; I got the names mixed up somehow (never used any of them, just heard about them a lot). The main point though is that “@param”-like syntax is already well-known by most people, and that’s great.

  5. @Jotaf : yeah the idea is to have something everybody’s comfortable with instead of inventing some specific system.
    “param : desc” would be nifty, but probably tricky to implement. What if I write “Note : don’t do that” in the function description, the generator will believe Note is a parameter …

  6. Hm, there wouldn’t be a problem if only parameter names are recognized; everything else (note, example, warning…) would be ignored that way. But then you’d have to parse the function signature, so yes it would be trickier 🙂

  7. Ah yes, indeed. Didn’t think about that. It’s true that doctcod is currently a fake doc generator ! It doesn’t parse the code, it simply convert the javadoc to html. That’s why you have to put the function signature in the javadoc, but that also required by the multi-language aspect…