I posted last week about running Doxygen from XCode using a custom build step.

I originally found a nice article on the Apple website here which describes how to do this, but it needed a little bit of tweaking, and wasn’t great, so I’ve improved the process a little bit.

First of all, I moved the bulk of the work into a script file, so that I can reuse it in multiple projects. This seems more sensible than cutting & pasting into every project. DRY principle!

I also decided to use a standard layout, relative to the project file, which meant that I could cut down on the number of variables that needed defining per-project.

My custom build step now just has to define a couple of variables and call on to the script.

You can find my version of the script here:

http://github.com/samdeane/code-snippets/blob/master/scripts/build-doxygen.sh

It could be cleaned up a lot more - it’s basically copied from Apple’s script then hacked a bit - I didn’t write it with public review in mind! One thing I fixed in the script was support for projects that have a space in their name or the name of a containing folder. Bloody unix programmers!

Second, I was annoyed by the output of the script, so I piped it into a file.

Finally, I was also annoyed at having to wait for the script to complete. Rebuilding the documentation each time is useful, but it’s not like you actually want to go and use it immediately.

So, I tweaked the build step to run it in the background.

Now my build step looks like this:

${WORKROOT}/scripts/xcode/build-doxygen.sh > “$TEMP_DIR/doxygen.output.log” 2> “$TEMP_DIR/doxygen.log” &

$WORKROOT is a variable that points to the root of my development folder - you can just replace it with the path to the build-doxygen.sh script file.

The script file itself relies on one extra variable - $DOXYGEN_ID - which I define in the project settings. It uses this to name the documentation bundle - so you should set it to something appropriate for the product - like com.yourcompany.yourproduct.

If you want to see the output of the script, you can add a second line:

open “$TEMP_DIR/doxygen.output.log”

This will launch Console and open the log file. Console is smart enough to update as the log file gets filled in, so it works even though the script may not have finished running by the time you open the log.

Update: one more thing…

By default XCode runs the build step every time. You can tell it to be a bit smarter by telling it what the input files and output files are for the step; it will then dependency check them.

I set the inputs to:

• $(SRCROOT)/Code
• $(WORKROOT)/scripts/xcode/build-doxygen.sh

And the output to:

• /Users/$(USER)/Library/Developer/Shared/Documentation/DocSets/$(DOXYGEN_ID).docset/Contents/Info.plist

Now, if you do something that doesn’t change the source code, the documentation shouldn’t rebuild.

I was wondering whether to use HeaderDoc or Doxygen for Objective-C project, and after a bit of googling I get the impression that HeaderDoc is on its way out.

I found a nice article on the Apple website here which describes how to get XCode to run Doxygen for you as part of your build, and turn the results into a DocSet which XCode knows about.

It works rather well, and the documentation for my test iPhone project now shows up in XCode along with the standard Apple sets.

One slight issue - I had to edit the script a bit to cope with having a space in the path to your project. It also has rather verbose output - adding –silent to the make command helps a bit, as does altering the doxygen.config to run quietly. Unfortunately the commands in the make file that Doxygen generates still seem to spit out a fair amount of crap even if everything is working.

One other problem - XCode can’t seem to find the documentation for a type when I option-click on it, in the way that it would do for an Apple type. This may just be a question of needing to rebuild my indexes though…

Over the holidays I’ve been messing about with the iPhone SDK, just for the hell of it.

I always prefer to have a project in mind when learning new tools, but I didn’t have much time, so I fairly randomly decided to do a little countdown application - something that tells you how long you’ve got before Christmas (for some reason this topic was on my mind).

The app itself was pretty simple to get going (less than a day), and doing the UI for the preferences has proved to be far more time consuming than the actual functionality! Once again I’ve been reminded how much fun it is to work with Objective-C / Cocoa.

If this had actually been intended as a commercial prospect, I’d have checked the iPhone store first, but luckily I always viewed it as a made-up project for test purposes only. Having said that I thought that I might conceivably post it to the store, just for the hell of it, so I went to have a look at the competition.

I figured that it was a totally unoriginal idea, so there’d probably be a few up there already. I wasn’t prepared, however, for there to be about forty! What’s more, I’d say that over half of them are paid apps (though costing only a dollar in all cases).

This is quite boggling, and it makes one wonder. Does anyone ever pay for these apps? Some of them have reviews, in some cases quite positive reviews, which suggests that they do. There are supposed to be more iPhones out there than Xbox 360s and PS3s put together. That’s quite a big market, but is it really big enough for 40 applications competing for a tiny and almost pointless niche? I’d love to know if anyone has sold more than 100 copies.

I guess the moral of the story is to check the store before you put any serious time into an application. Although, perhaps not. Perhaps the moral is to check the store, rip off the good features of your competition, then do the app anyway because it’s a big, big, market. Or maybe not!

(absolutely quite a bit, actually, say it again)

James at work said yesterday that often he finds, paradoxically, the code that is best documented is also the code that needs documentation the least, since it tends to be well designed and written in the first place.

I know what he meant, and it rang a little bell with me (although whether my code falls into that category is for others to judge :) ).

In lots of the places I’ve worked I’ve tended to be one of the few people who writes documentation, and I often wonder whether anyone else reads it. Is it, perhaps, all a monumental waste of time?

That said (and when I’m not having a bad day), I believe that to worry too much about whether it gets used would be to miss the fundamental point.

The reasons that I write documentation, in order of importance, are:

• to clarify what I’m trying to do
• to clarify why I’m trying to do it
• to offer up my design for peer review
• to explain my implementation choices
• to note avenues that I’ve tried and rejected, to avoid others doing the same
• to help other people use what I’ve done

If anything, the “why?” is even more important that the “what?”. Spend a bit of thought on that one, and the rest may turn out to be irrelevant.

In any case, having other people use the documentation as a reference comes pretty far down the list of priorities.

Which doesn’t mean that I don’t want people to do that (it would really help, frankly, if more people would RTFM!). It does mean though that I’m not going to lose too much sleep if I feel that I’m the only one reading what I write.

At the end of the day, writing documentation, for me, is an essential part of the process of writing software, especially when working with others. How can you code a system that you can’t describe in words or pictures?

Having other people read it is just a bonus.

Last night, with a bit of trepidation, I let my eee 901 hackintosh upgrade itself to MacOS 10.5.7. I’d been putting it off for fear that I might end up with a non-bootable machine (I could have recovered from it, but it would have been a pain).

As luck would have it, it mostly worked ok.

After reboot, the main problem that I had was that the monitor settings had reverted to 1024 x 768, causing the top & bottom of the screen to be cut off. Since the Mac menubar is at the top, this was a bit of a snag, but luckily I know the layout of everything pretty well, and I also had the advantage of Spotlight. Hitting Cmd-Space brings up the spotlight search box (in the right place, interestingly, even though the menubar was in the wrong place), and typing the name of an application allows you to launch it.

After a bit of experimenting, I ended up just re-installed the kexts from the EEE-Utilities package put together by Gregory Cohen. This seems to have sorted everything out.