Consider relaxing the requirements for JavaDoc in the project

[bitwiseman]

Per discussion with @nedtwigg in #1290 , it might make sense to turn down the warning/linting level for javadoc in the project.

I love when javadoc has example inputs/outputs (this project scores 10/10 there) but I'm annoyed by rigid compliance with a javadoc linter forcing that gold to get diluted with "returns the value" boilerplate.

and

Not great but compliant is still better than non-compliant.

Why? I do a lot of work on Spotless, because I think formatting doesn't matter and I don't want to talk about formatting.

When it comes to documentation, I think it does matter, and so it's worth talking about. Automated tools can't say obviously getFoo() returns foo vs it's interesting that getFoo() returns a String guaranteed to start with 'git://'. So whether or not the documentation adds information beyond what's already in the name and type signature of the method is a human judgement call (for now, copilot is coming for us!). IMO, automated enforcement of

• does this documentation add information? -> return true, always document everything, users don't need to read the implementation

isn't much better than

• does this documentation add information? -> return false, never document anything, users need to read the implementation

If you add options.addStringOption('Xdoclint:none', '-quiet') then it will still error for undefined @link and things like that, but it lets "(to / not to) document" be the judgement call that imo it should be.

</unsolicitedopinion>

and

could you open an issue for this

I've thought a lot about this topic, and I don't have any more to add besides this:

• Train a low-parameter neural net on the dataset function name+signature -> javadoc for your project.
• For each javadoc, diff the neural net's prediction against what the javadoc actually is
• Remove all the identical parts of the javadoc

I don't plan to build this, but imo that's the way I would think about it. Happy documenting ;-)