This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.
And every other modern language, be it statically typed or dynamic (with the help of annotations), has had some sort of auto-documentation generator either bundled or at package manager's reach, and probably any can top javadoc in many ways.
The frustration pointed out by OP is that when you see a page of "blank" generated documentation you never know if there is valuable information waiting for you maybe just one or two clicks away or if it's placeholders all the way down. Consuming a sparsely filled doc almost feels like being trapped in an illustration of the halting problem.
A javadoc/-like implementation that somehow put the actually authored subset into the spotlight while not completely skipping the inferred bits could be very valuable.
(also: a javadoc/-like compiler that detects as much delegation as possible and aggressively pulls in stronger documentation when it is available further up or down the call nesting)
Still better than 90% of projects/libs at the time, who didn't have any reference documentation at all.
Just seeing the signatures and packages in an organized manner with cross links (e.g. to parent class, implementing classes) etc, was a vast improvement...
In Hoogle, I can type `Map k v -> (v -> Bool) -> Map k v` into the search bar, and it finds the function, even though I got the order of the arguments wrong.
https://hoogle.haskell.org/?hoogle=Map%20k%20v%20-%3E%20(v%2...
When you're looking for functions, do you generally use Hoogle, or do you have a local autocomplete-like feature hooked in to your editor? I really want to be able to use this while writing code.
Pure languages get a lot of hate, but this is the kind of thing you get when you enable better static analysis of your code.
This is something I think rustdoc (for rust) also has succeeded at, partially for similar reasons.
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.
Especially in the enterprise world, I often come across completely useless code docs, created purely to satisfy SonarCloud or an otherwise stupidly dogmatic gated checkin of the "all public methods must have code docs!" variety. I'm sure many of us have come across it - code docs for a constructor that say "Constructs a Widget", or for an `AddWidget` method that says "Adds a Widget"; utterly pointless. I think of this as "dogma driven documentation".
Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation.
You have to write your documentation, keep it up to date and take it seriously. I would argue, if you have auto-documentation you are more likely to miss that, because you have some kind of documentation somehow - irregardless if it's actually useful.
If I'm looking at documentation, I want the inputs and outputs and a brief description of what it does. I care very little about the implementation, or I would write my own.
Rust for example also warns about code included in the doc comments example section which is invalid.
Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.
It checks for rust snippets in markdown files and attempts to build them when you run `cargo test`. It helps keep docs and code in sync.
Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.
Even if you have great inline documentation that can be turned into a great external reference document, you need separate documentation.