Interesting, because when I switched to Java I absolutely hated (and still do!) the autogenerated documentation. Included was every variation of the constructo

Interesting, because when I switched to Java I absolutely hated (and still do!) the autogenerated documentation. Included was every variation of the constructor. Missing was HOW I would actually call it, and where I would get the params to it. It's been the better part of a decade, so I can't actually quote correct APIs, but I recall trying to connect to an LDAP server - I just needed to call one of four constructor methods, which seemed to imply I needed an LDAPContext object. Looking at that object told me the 10 bajillion values it had, but no idea how to set them. Once I saw an _Example_, which IIRC was basically calling a method to clone the default context object and setting the one or two params (such as server url), I could then pass that to one of the constructors I saw the docs for. The generated documentation was 100% _correct_, but not _useful_. Other languages I had been in had very example-focused documentation, and were far more accessible and usable as a result, even with occasional challenges where the docs might slip behind - that almost always tended to be corner cases, while the Java approach made the most common need into a corner case.