There are many things to like about the emacs documentation. Maybe I should list some of them here, just to make this clear....
One thing that's great about the emacs lisp documentation is its resounding clarity, its self-evident, radiant aura of completeness. You get the sense that everything you could possibly need to know is right there.
Unfortunately, this is not quite true. Often you get the feeling you've been told everything, but some thought reveals ambiguities that can only be resolved with experimentation.
A simple -- and relatively trivial -- example is looking at the doc string for a command, and being told that it returns a filename. But... is that a filename with or without a path? Better check that detail. Because if you forget you could get stuck scratching your head for hours trying to figure out why a simple regexp that begins with a "^" won't match the filenames that you think it should. Hint: "^\\(.\\)" is always a "/" if you've got a listing of files with absolute paths on them. If you want to capture the basename, you might want a pattern like "/\\([^/]*?\\)$". You definitely don't want one like "^\([^/]*?\\)$".
Luckilly, I'd never make a bonehead mistake like that.
For more whining, see the rest of The Whinery