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.
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.
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".
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.
This is something I think rustdoc (for rust) also has succeeded at, partially for similar reasons.
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.
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.
Rust for example also warns about code included in the doc comments example section which is invalid.
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.
Even if you have great inline documentation that can be turned into a great external reference document, you need separate documentation.
... Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me.
... The api documentation for [product] can be found here: https://api.[product].com/
... Sorry. That's not what I mean by "documentation". It's certainly non-linear. I don't know how to "read" this site to gain an understanding. It's kinda sparse:
GET /v2/adjustments > Implementation Notes: Fetches a list of adjustments.
GET /v2/reportCategories > Implementation Notes: Fetches a list of report categories.
... "Swagger Documentation" is a special class of documentation for sure; Nobody likes writing documentation.
Talk about insider (them)/outsider (me).
If you need to add data to one endpoint and see how that travels to other endpoints, that makes sense as to why you want documentation. In that case, a product / API tutorial or recipe (like the author suggests) might be useful.
Instead, we often get nothing but a method name and argument types. Ridiculous.
Because those who control resources make a conscious decision to prioritize new features and/or bug fixes rather than documenting what exists already.
The problem comes months later when I'm in the weeds and a colleague asks a question. I try to fob them off to the documentation, but some details are out of date. I pray it's just one detail, and that I don't have to stop what I'm doing to rewrite the documentation now.
# <PROJECT NAME> Service
This is the new service for <TASK>.
....I could buy a good README.
Sure, if documentation is treated as an afterthought it tends to reflect that attitude.
For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.
I mean, with actual code you get some help from the tools. No silver bullet, but at least you have type checks, compiler errors, something. But with docs there's no way to automate checks to see if the doc is still relevant and accurate. And what terrible tools are there tend to lead to "boilerplate docs", like those javadocs mentioned in a comment elsewhere.
I've been wanting some kind of system to add references to tests to documentation, in the spirit of citation. Maybe I will build it at some point.
Bingo.
Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.
Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it.
Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing.
I'm a bit of an extreme case, but Many engineers feel so incredibly uncomfortable with writing prose that they avoid it. Why? The standard of writing education for STEM-minded people is low. Why? Writing education in high school is focused on literary analysis essays rather than on learning to describe facts and systems with vibrant clarity.
[1] https://getputpost.co/overhauling-api-docs-with-gocardless-9... ---
Anecdote: At age 14, my school had poster which listed the professions one could use mathematics in. Someone pitched us on how much need there was for people who could program. Shop classes and science classes had assignments which were miniature versions of problems we could see in the real world. Nobody did this for literary analysis. I didn't know how to ask "why are we doing this?" other than as a snotty teenager saying "Hey english teacher! Justify why your life's work has meaning." In reality, I wanted to say "I'm having trouble getting oriented around this subject. I'm having trouble understanding what it means to make progress or make something good. Can you help me?"
I searched for writing advice devoured works like Politics and the English Language and Strunk and White. But they just helped me get better at editing, not at putting thoughts onto a blank page.
Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring." At age 17, I didn't have the self-confidence to persist to find a different teacher who would be interested in that.
Anecdote: At age 20, in an engineering university, I knew that I struggled with getting the first draft of an essay done. I went to the writing center at my school. But I never built a good workflow with them for how to get the first-draft-writing process. I didn't know how to learn to write without an anxiety so strong that I felt compelled to dig my nails into my skin. I didn't know how to ask professors or TAs for help. I accepted that writing was just staring at the paper until my eyes bled. I wasn't going to learn to write. I endured my required writing classes. hoped that once I graduated, I might be able to work in a way to
Anecdote: At age 29, I had to quit a visa-sponsoring software engineering job and very quickly find a new one, because of my failures with writing first drafts interacted with a business process for immigration-law compliance.
---
I've now found two coaches and plan to spend this Saturday working on a first draft of a blog post and trying some of their strategies. Wish me luck.
I laughed and then I got sad
I've actually written some pretty long comments on reddit. Yesterday, I talked with one of my coaches and put some thought into why:
1) I don't have any memories of feeling anxiousness from commenting on reddit. This is unsurprising since it has never been assigned to me by a teacher/parent. If I ever feel like "Its unclear why I would respond to this or what I would say to this", I just choose not to comment.
2) I have memories of writing a comment and other people upvoting it or telling me that it was helpful. I don't have this for essays. I driven by making people happy, so that is a meaningful reward.
3) Because of those positive memories, as I am writing, I can imagine that a sentence I am about to write is going to be helpful. That imagining is a bit of positive re-enforcement that I can chase, inherent to the task. It is like when I was a kid and I would do math homework and I would solve a problem and see that I'd solved it. It is one of the tricks of TDD.
So, my plan this Saturday is to seek out the things that could possibly be intrinsically rewarding about writing:
A) Look for interesting phrases that I can craft to clearly explain something.
B) When I start on a section, write a question that someone could ask on a reddit thread, which this section answers.
C) When I write a section, imagine myself saying this as an explanation in response to that question and imagine someone else expressing gratitude for that explanation.
D) To avoid procrastination, mentally rehearse the act of starting and getting into the task. Simulate the trigger-response-reward in my mind so I can build the neural pathway. The reward I imagine should not be tied to completion, but come from the "I've just gotten started" state.
Good documentation, enabling user self-support, eats both cost and revenue.
(To what extent this is a conscious strategey and not simply decades-of-experience-born cynicism, I'm not entirely sure.)
This from the Rust standard library is a good example - https://doc.rust-lang.org/std/result/index.html . I think that's great documentation, and it's entirely generated from the source code.
Most rust libraries won't have this level of explanatory detail, the core team have put a lot of effort into making it as easy as possible to learn, and documentation effort is part of that (the Rust book is another important part).
Something else that Rust does well is that 'examples' is a standard part of project layout. For libraries that haven't done their top level documentation well, the examples folder will usually give a good demonstration of how to use the code, and they usually exist because that's the easiest thing for the library author, and the usually compile because they're automatically built by `cargo build`.
For most applications this approach is generally useless and should not be used. Comments should be in the code itself, and you expect people who want to work on the application to read at least some of the code. I.e. no reference / API documentation for applications, instead high level overview (where is what, application architecture etc.) and guides (how to set up your dev environment, how to contribute, how to prepare releases etc.).
For libraries it often makes sense to generate a reference documentation from the code itself. The drawback is that the strictly formulaic nature of comments parsed by the documentation generator has to be always kept in mind when writing the code itself. I.e. the comments need to make sense and be comprehensive when you remove them from the code surrounding them.
Some modules in the Python standard library are a good example of this. Quite a large amount of prose, separate from the code, and then a reference section generated from code. However, many modules have pretty bad documentation, where even the reference is missing crucial information (quite often very basic things like what a function returns).
Rust handles this nicely; its generated docs are based off source code comments. Same with Golang.
Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
If I'm a consumer of some third-party API, there's no practical difference between intended behavior, accidental mutation and a bug which the supplier won't fix any time soon - all of these things are equally part of the contract of how The Thing v1.2.3 works, and that's what I want described in the documentation. Any part of the documentation that says what The Thing should do (but doesn't actually do) is worse than useless, it's actively misleading; it describes some wishful thinking with no connection to reality.
If the contract documentation describes an interface between two parts of the system that I control, and I have the ability to fix discrepancies between contract and code by altering the code, then sure, that's a different situation; but if I don't have the ability to make these changes because it's an API to code made, maintained and controlled by someone else, then accurately describing current reality is the most important thing.
Likewise if v1.2.3 has a bug I want to know to not rely on that because I'll probably update to 1.2.4 which fixes it.
I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`.
Vertx web api contract router. Which takes in a swagger file, and routes based on the `swagger` operation id. Is the closet I've seen. https://vertx.io/docs/vertx-web-api-contract/kotlin
I've also written a library to route into ktor in a type safe way.
But if you're doing swagger. To me it should be written, then consumed by the back-end service. Then generate front-end clients. Anything less will result in bugs.
I've seen companies pile on so many services. To double check code generated swagger. Hit a bug, then have to maintain the swagger spec outside and not enforce it.
This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it.
I've written a couple of libraries that do exactly this:
https://github.com/eropple/nestjs-openapi3 - OpenAPI3 library for NestJS that standardizes input validation
https://github.com/modern-project/modern-ruby - a Ruby web framework built around OAS3 concepts + rigorous validation
less code, standard approach, less bugs.
A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.
Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.
[1] https://help.github.com/en/articles/creating-a-pull-request-...
Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like:
public class BookStore {
...
/**
* @param book The book.
* @return The price.
*/
public static float getPrice(Book book) {
return book.price()
}
}
Not a contrived example. There are an absurd amount of libraries that do this and call it documentation. There will be a nice, tidy example of how to use the library with a toy example. That's fine. The intro probably doesn't need to go that deep. Then I move to the technical documentation or API, and that's what they have to offer.
Of course, the other side of this coin is that without these draconian build processes I probably wouldn't write the useful kinds of javadocs I write for significant methods.
Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and write narrative and have it get nicely collected into a slick hyperlinked webpage by things like doxygen and Sphinx, then that's great.
There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.
It is a completely different situation from the lack of such a comment, that implies that the author didn't stop to consider the function, and you can find any kind of strange things when calling it.
y++; // Bump y
y++; // Do we need error checking for top of y axis?Just like you can write bad code, you can write bad docs, not update them etc.
The point of code generated documentation is not to render the interfaces but rather to keep code and docs in sync in the same place. It's more likely you'll se an out of sync / undocumented piece during a code review, in context, etc. then to assume it was updated somewhere else.
Many people hate auto-generated API documentation because library authors do not write enough of it.
For example here are my project's auto-generated documentation from source code, for two classes:
https://gojs.net/latest/api/symbols/Diagram.html
https://gojs.net/latest/api/symbols/GraphObject.html
That's 1238 words and 1408 words before you even get to the constructor.
There should be a lot of information that comes out of the auto-generated API: What it is, what to know, different kinds of classes interact, and where to go next.
Then of course a primary tutorial: https://gojs.net/latest/learn/index.html
And then conceptual Intro pages: https://gojs.net/latest/intro/index.html (62 of them, covering everything from high level concepts to printing)
Then, since so many people learn by example, hundreds of samples, organized with pictures and tags for each, with an explanation and commented code: https://gojs.net/latest/samples/index.html
Why do you think it's useless? What part is useless? I am considering taking on this project at some point in the future.
Edit: also I am referring to a library's API while I think you refer to a RESTful API. Would your comment also apply to libraries's API?
Unfortunately, in my experience a lot of devs turn on auto docs in their project's settings and call it a day, especially if it's not a library/API!
Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me no-content auto-generated documentation is a real code smell.