I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time.
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.
I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.
The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not. Or worse: (pre-)filled with redundant placeholders like "@return returns the $Typename".
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)
>The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not.
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...
Sure. Even the most sparsely populated javadoc suddenly turns from a nightmare into a valuable improvement when you stop trying to pull information with a browser and just enjoy what the IDE presents when implementing an API client, if it is presenting something. More authored content is still better than less, but the amount of empties remaining stops being a hindrance when consumed through an opportunistic push mechanism.
This is also a great feature of Haskell, especially Hoogle, which is what I miss the most when working in Java. If I want to find a function which, say, removes items from a Map based on a function over values, in Java I have to look and see if it's in the Map class. Nope. Is it in Guava Maps? Ah, there it is, "filterValues".
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.
I'm impressed. Being able to search for functionality by the function signature seems incredibly useful. In the "Verb-Noun vs Noun-Verb" thread from a couple days ago [0], people were saying that OO languages make autocomplete much easier because you start with the parameter you're operating on. But, autocomplete (at least in IntelliJ) only lets you search by method name. There have been lots of times where I want to search by return type or param type instead.
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.
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.
At the end of the day, it's up to the developer to provide useful documentation.
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".
I'll definitely assert that Rust has nailed the automatic generation of documentation from comments in source code. It's a somewhat unusual language so getting used to how the docs are laid out toook a bit of time, but once I was using the language, the docs are the best I've ever used. Some examples:
Typedoc [1] is an excellent documentation generator for Typescript.
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 .NET standard library docs are a thing of beauty because they intermingle autogenerated javadoc-style documentation with generally well-written freeform "remarks" sections that include more general explanations, context, and code samples.
I've struggled through doxygen generated docs for C++ before, and I think one of the things that helps make javadoc more readable is due to the "stricter" (in a sense) structuring of the java language vs C++: namespaces & objects everywhere make grouping more likely to occur in consistent ways in the code base, which then gets translated to more readable auto-generated documentation.
This is something I think rustdoc (for rust) also has succeeded at, partially for similar reasons.
> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time.
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.
With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!
I'm sure you know because you're Steve Klabnik, but for other readers: you can enforce documentation for public items in a crate by adding `#![deny(missing_docs)]` to the `lib.rs` file.
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.
For abstract descriptions of what the code does, sure. But for small things like documenting the purpose of arguments, an IDE should warn about changes that are not reflected in the doc comment (type or a new arg altogether). IntelliJ IDEs are pretty good at that.
Rust for example also warns about code included in the doc comments example section which is invalid.
Mostly it collates all your endpoints more easily, generates clients for different languages, genearates an online documentation and test page that makes your service self describing, and can be published out to third parties that dont have access to your code.
The tool parses out the bits that you're interested in. If you want to know what year the proverbial apple fell on Isaac Newton's head, you can get a biography and start reading, or you can Google and let the machine filter out the irrelevant bits.
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.
The article talks about four kinds of necessary documentation for large projects: explanation, reference, how-to guides, and tutorials. Auto-generated docs, even when they're very good, only provide one of those -- the reference.
Even if you have great inline documentation that can be turned into a great external reference document, you need separate documentation.
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.