Raymond Chen has been running a series of interesting articles about the history of Windows and its API. Ever wonder why the time zone map no longer highlights the zone you're in? Or what the BEAR35, BUNNY73, and PIGLET12 functions are named after? Or why you turn off your computer by clicking “start”? I've bookmarked his site.
In particular, The secret life of GetWindowText should be required reading for anyone trying to understand API lockin. Describing one aspect of this simple and fundamental part of the Windows API takes a couple of pages. And then notice the kicker:
The documentation simplifies this as “GetWindowText() cannot retrieve text from a window from another application.”
As Raymond says, the documentation tries to explain its complexity with small words, which is great if you don't understand long words, but it also means that you're not getting the full story. (Actually, Raymond, the documentation does tell the whole story, look closer.)
Anyway, the complexity behind such a simple function is a classic example of an abstraction leaking. And more importantly, it's one of the reasons it's so dang hard to write API emulation layers, like, say, WINE… because getting 100% compatibility means emulating all these bizarre internal complexities perfectly, even when they're not completely documented or the documentation doesn't really describe what happens in every scenario. [Joel on Software]