Hi Igniters,
We use JDK Javadoc tool to validate javadocs on TC (Javadoc suite) in
Ignite 2 and now in Ignite 3.
A javadoc tool is designed for javadoc site generation that also performs
some basic checks and markup validation,
but has nothing to do with javadoc styles.
I've found maven-checkstyle-plugin has modules for javadoc style checking,
which looks more suited for the issue.
I've tried to turn on javadoc checks in checkstyle plugin, then run it
against Ignite-3 main branch and got 1200+ errors.
For Ignite-2 thing may goes worse and numbers can be much higher,
but let please, start a separate discussion for this if one feels it make
sense.
Javadoc is part of documentation which a face of product and we MUST keep
high standards for javadocs as well.
Let's improve this within the ticket [1] regarding the next suggestions:
1. Add Javadoc checks to mavan-checkstyle-plugin. I've made a PR for
Ignite-3 [1] to turn on style checks for javadocs.
2. Keep the current Javadoc TC suite as is. because it allow detecting
markup errors regarding current javadoc tool version capabilities.
3. Fix the Codestyle guidelines to follow higher standards.
3.1. Disallow empty javadocs (or with missed description) for member that
can be used outside the class/package/module by users or other developers.
I believe all methods/classes/fields that can be used by developers
(public, protected, package visible) MUST have meaningful description,
excepts may be tests, well-known constants (e.g. serialVersionUid), and
private members.
Actually, it not a big deal to put few words into javadoc even if the
method looks simple,
if one feels difficulties expressing a class/method purpose, then most
likely refactoring is needed.
3.2. Check all params/throws/returns/generics/deprecates MUST be
well-documented and goes in order.
3.4. Suggest to allow optional tags @apiNote, @implSpec, @implNote as
described in [3],
to put e.g. expectations/requirements of implementation for developers that
may be non-obvious.
The tags values are rendered in separate blocks on javadoc site.
3.5 However, one-liner javadoc like "{@inheritDoc}" does nothing and can be
safely omitted. I'd keep it.
3.6 Add javadoc checks for 'package-info'. Do we want an additional
requirement to every package has package-info?
Working on the patch I've found it is impossible to have different policies
in the same config for different scopes: source and test code.
Thus, we can either exclude tests from style checks at all, which looks
like not a good idea,
or have different configs with different policies for source and test code.
Any thoughts?
[1] https://issues.apache.org/jira/browse/IGNITE-14591
[2] https://github.com/apache/ignite-3/pull/98
[3] http://openjdk.java.net/jeps/8068562
--
Best regards,
Andrey V. Mashenkov
