Hi Alexandria, thanks for your reply!

The issue with the documentation page that I linked to in my original post is that it has a prominent link labeled "Documentation." When you click that link, you end up in precisely the same place. The only reasonable conclusion is that the site is badly broken. After I followed your link to the list of classes, I was able to figure out how to drill down to that information. But it's far from obvious that that's even possible, especially when the big link labeled documentation doesn't do anything. Plus, I would expect a documentation page to contain, at minimum, a table of contents directly in the main content of the page (not the sidebar). How else can I know that I'm in the right place?

When it comes to code examples, they're only useful in specific situations--HOWTO articles, for example. The main reason that projects which conflate examples with documentation tend to earn my ire is that examples only help if they cover exactly what I'm trying to accomplish. Any difference, however slight, and an example won't help. Proper documentation consists of descriptions of how the various systems work together with comprehensive documentation of each class and public method. Example code, again, can be helpful if it is presented as a part of this documentation, but it can't stand alone.