Like everyone other Mac developer (at least, those not using a seed… no comment otherwise), I’ve been bit by the Mac OS X 10.5.7 bug that causes Xcode to crash almost every time the documentation viewer is used.

Now I’m a reasonable guy. I get that a Mac OS X update has to be thoroughly tested. I wouldn’t want it otherwise. So let me get this off my chest right away: it isn’t the bug itself that bothers me.

Xcode 3.1.3 shipped after Mac OS X 10.5.7. So it should have been pretty easy to add code to Xcode see if the developer has executed a defaults write com.apple.xcode dontevershowthefuckingdocviewer 1 and then never show the documentation viewer, so I wouldn’t lose unsaved work every time I forgot and tried to open it.¹

And in the future, the documentation links should be handled via an URL type that can be handled by another application.

And, oh yeah:

Why is the documentation viewer embedded in the IDE?

Splitting the documentation viewer into a separate application would make a lot of sense. Browsers crash! If it wasn’t this, it would be something else that crashed the documentation viewer. This was predictable. This was, dare I say, expected.

But what really, really makes me angry is the developer site. The content is generally pretty good, but the search engine is horrible:

• Fix your summary so it’s actually useful.

  Apple’s summary:

  Google’s summary:

  

  There’s just no comparison.²

• I don’t need to see every single empty redirect. Showing the same effective document multiple times is just random clutter.
• There are better ways to represent the format of documentation in search results than just including it in the URL.
• Add up those last two items, and you realize: I don’t need PDFs in the search results. PDF should just be linked to from the documentation itself.

I’ll update this when I have more points. The bile has receded enough for me to code again.

1. Maybe use a different identifier for it.
2. Google, you rock.

However, a problem arises when you’re creating a lot of objects at once. The obvious solution is to initialise and release objects by hand in this case, but sometimes it isn’t possible. A lot of objects returned by Cocoa methods are autoreleased (by convention any object returned by a class method (other than +new or +alloc) should be autoreleased).

This is a good practical example of autorelease pool manipulation, including numbers showing before and after.

What’s so confusing about it? You really need to see how it interacts with the iCal main window to understand. We’re going to be focusing on the group starting with “Hide Calendar List.”

The iCal main window looks like this:

The sidebar on the left side of the screen looks simple enough. Now let’s look again at the menu. What would you expect Hide Calendar List to do?

Wrong. It does this:

Both the calendar and mini month calendar are hidden. Hiding both makes sense, but calling the command Hide Calendar List doesn’t. Go back to the menu, and we see the helpful command “Hide Mini Months.” What Mini Months? Oh, the ones that were on the iCal window, but aren’t anymore? I wonder what it does?

It does this:

That’s right. Choosing Hide Mini Months showed the mini calendar.

So here’s how the menu commands work:

The first command, Show/Hide Calendar List, hides the entire left side bar: The calendar list and whatever is under it.

The second and third commands, Show/Hide Mini Months/Notifications, control what’s under the calendar list, but still controlled with the Show/Hide Calendar List command. And they don’t actually do what they say they’re going to do if the calendar lis is hidden. They’re mutually exclusive: Think of them as Under Calendar List: None, Mini Months, or Notifications.

The fourth and fifth items are entirely independent of the first three items.

Granted, coming up with menu commands to control a UI like this is hard. But that’s no excuse to throw your hands in the air and settle on this UI.