Hey! That's every JavaDocs I've ever encountered. See the Apple CoreAudio docs for instance. Auto-generated and never revisited.
Such doc systems are a crime - the Manager asks "Is the documentation complete?" and then Engineer says "Well the auto-docs were created but..." and the Manager says "Good, lets move on"
I've yet to see anybody that really bothers writing comments or documentation, and, more importantly, keeps it updated to match reality. This is only getting worse these days, where even major libraries and frameworks from Fortune 50 companies barely have autogen'd javadoc-style information available.
"API doc autogeneration; I can guarantee that if anyone came up with a default tool with default output such that "doctool module html_directory" was all you needed (and indeed people have) then there would be widespread, perfectly legitimate, disagreement on any number of choices in the design of it."
In my experience, the opposite actually happens. When something is written, people either use it and customize it over time, or they just find something else and say it didn't suit their needs.
It's when an extremely useful/general library is PROPOSED that it becomes a huge disagreement. This is, for instance, why C++'s Boost still doesn't have logging or a unified XML library, and won't likely have a garbage collection library before a C++ TR defines the interface: everyone argues over the color of the bikeshed, and the people who try to write the libraries get caught up in infinite microdiscussions over details.
Conversely, someone like Linus Torvald's success is that he just makes the things he needs/wants (ignoring bikeshed discussions), and people generally end up using his creations. When it comes to software design, a dictatorship is often more productive than a democracy!
"When I come across pages of JavaDoc-ish API documentation, I groan internally and just look at the source instead."
Plus you cannot really automate checks for documentation up-to-dateness.
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.
As developer it's even worst, it's possible to develop module for the Blackboard platform and I had once to develop a module for that. Be aware you will see the worst documentation ever, even if you have access to all of it. 2 websites for the exact same thing, in which you have a zombie forum, a wiki in which there are a lot of empty pages, a lot of document which repeat almost the same exact example, etc. The platform is in Java ... and they don't provide the JavaDoc. Good thing I was paid, otherwise there is no way on earth I would have torture myself to do that thing.
Note: I wasn't working for Blackboard, but an other company which had got a contract to do a module for the Blackboard platform.
Oh I wish. I have only heard all these jokes about being forced to write useless docs but I have yet to see a place where there are docs when I try to get into the projects someone left me.
Wow, I think that's my new go to example for bad documentation.
That may actually be worse than no documentation because you wasted time looking for what is in essence a mere repeating of the function call and nothing else.
This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody reads it.
And nobody reads it because there's so much of it and there's no clear starting point. People just want the summary of what they're looking for.
I started to learn Java almost 20 years ago, we had a text book and everything. After the first two chapters, I learned how to google and instead of reading everything, just find what I need. I never went in-depth with reading because... it's mostly useless knowledge that quickly becomes outdated.
It generates auto-docs, which are useful. It's just a ridiculously verbose way to do it, and it would be preferable if the documentation could be generated without the repetitive comment.
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
It's a common use-case that the best docs are provided on some dude's gist or blogpost. Devs and orgs update the code but don't bother with the forgotten docs. It happens all the time.
They also suffered the same problem mentioned in this post.
Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.
Coming from the same perspective, I agree completely.
Software pushers all seem to give the same puzzled look when I ask to see their full docs before evaluating their product.
It's exactly as you describe, if the documentation isn't sufficient for me to learn everything I could possibly need and likely want to know about how things work - I can't confidently design, build, scale or support it.
Documentation in the "Enterprise" world seems almost intentionally bad, as if to force customers into professional services and support contracts for products which lack the proper design to be sold as full on SaaS.
My pet-peeve is technical documentation that is not versioned with the code. I think you're confusing garbage-in / garbage-out or interface rendering with auto-"generated" documentation.
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.
Are you really arguing that you shouldn't have to study documentation? First, blog posts and code samples are not documentation (in this case, at least).
If you were working for me as a developer and had the attitude that you shouldn't have to _thoroughly_ read the manual and notes for something like MongoDB, I'd let you go. Steve Jobs was not a programmer.
Such doc systems are a crime - the Manager asks "Is the documentation complete?" and then Engineer says "Well the auto-docs were created but..." and the Manager says "Good, lets move on"
reply