Comment by tliltocatl
5 days ago
No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.
Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.
Of course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.
I agree. I don't understand some of the black and white thinking in the comments.