[SomeCallMeTim]

The example that he gives that I take issue with is the "Constructor" one in a JavaDoc comment.

When using documentation tools, every undocumented function spews a warning. And that is as it should be. But some simple constructors don't have any functionality worth documenting.

I code as if all warnings should be addressed, and that's true of my documentation generation. If a public function has no documentation, that should be considered an error that needs fixing. If the documentation is obvious, then so be it.

That is the price you pay for reliably good documentation; without enabling those warnings you don't know when you've missed documenting an important function. And even sometimes the "obvious" is useful; I don't know how many ambiguous Boolean parameters I've seen where it wasn't clear what value "true" represented.

[ianstormtaylor]

+1 I'd much rather side with the "document every function" camp and have a few extra comments, than inevitably degrade to the "document close to nothing" camp and have functions named "normalize" and "resolve" that have to be in their entirety to understand what they do. That being said, I like to drop the `@return void` and `@api public` type entries because they're almost always self-evident, or even not true, like in Javascript where everything is public if exposed and people will reach in no matter what you do.

Writing docblocks can also be a nice way to check yourself from writing bad code. If you find yourself adding 4 different `@param` entries it makes you stop and think, "why is my function taking 4 arguments, it's probably poorly designed".

[mjmahone17]

If you're only documenting after the fact, your function isn't worth documenting: it means you conceptually understood it well enough that you didn't have to think much about it's inputs or outputs. If you did have to think through it, or your code reviewer doesn't understand it, add a comment explaining it. In any other case, commenting on it is probably useless and adding to clutter. Javadocs are painful to read, not because it's a bad idea, but because so often it's things like "toString(): returns a string that is the string of this object". Sorry, I only need to know that function exists and it's return. I want to be able to scan through and see only those functions that are conceptually strange or unique, not the boilerplate that every class has to have, and is identical. If there's a comment on the toString() function, it had better be documenting something interesting, or else it's more useless than nothing.

[SomeCallMeTim]

>If you're only documenting after the fact, your function isn't worth documenting

I can't disagree more. You can completely understand what you intend as you're writing a function, and then later, as you look back with a fresh perspective, realize in what way(s) the function could be misunderstood.

>Javadocs are painful to read, not because it's a bad idea, but because so often it's things like "toString(): returns a string that is the string of this object".

Straw man. "Bad docs are painful to read." Sure they are. If you have good documentation practices, you'll explain in toString() HOW the object is represented. "Return A string that indicates the (derived) object type, its x,y coordinates, and its current state, along with any additional state specific to the derived object type. You should not rely on its precise format, as it may change in the future."

The real problem is that most documentation sucks. But the only way that developers will ever get better at documentation is to practice.

I also am confused as to why "scanning" JavaDocs would ever need to be a thing; you do end up with your JavaDocs as a web page or help file, right?

If I'm confused about a function, I want to be able to click on it and see docs; if there are no docs on half the functions, that's a failure of the imagination of the API author(s). If they can't see how someone might be confused, and yet I'm confused, then they blew it.