Yes, I've seen it Clojure, where the documentation is extensive, giving great coverage to its standard library... but still haves you reading the source and searching the web for examples after reading the description, especially when speaking about macros (so... does this receive a vector? Does it take its arguments as a list, or what? A mixture of both?)
Racket goes full in the other direction, to a fault, even though it's much preferable.Racket's documentation is at times hard to wade through because it's so extensive. You have to scroll through the treatises and descriptions of options to find an example usage which will get you out quickly, but it's, for once, all there in the manual.
Haha, I actually really like how Racket does it and consider them a great example to follow:
- Racket's documentation is all on your local machine. Stuck without an Internet connection? F1, and you're searching your own documnetation index.
- Everything -- everything -- is hypelinked. If you see a blue word in a code example, even the ones on the front page of http://racket-lang.org/ , you can click on it and jump straight to that function's contract.
But I agree, I wish there were a better way to jump straight to examples when you're looking at a specific function's documentation. It's confusing having the completely separate "Guide" and "Reference" halves of the documentation with no links between them.
My gripe with Racket's documentation is that there is no middle ground between tutorials designed to showcase features rather than explain how Racket does and doesn't work and computer generated auto-docs. The tutorials are more geared toward selling the language to beginners, while the rest of the documentation is bereft of illustrative examples and editorial discussion.
A++ is a grade, not a number. Clearly what you need is #S(grade :letter A :decorations (+ +) :rapidly-escalating-pedantry t) or some other meaningful representation.