I personally do not understand why we need mandatory javadoc even in public
modules. I think javadoc is needed only when the code is not
self-descriptive. What value does a javadoc like this bring
<https://github.com/apache/ignite/blob/2.10.0/modules/core/src/main/java/org/apache/ignite/configuration/IgniteConfiguration.java>
to a developer:
/** Default metrics history size (value is {@code 10000}). */
public static final int DFLT_METRICS_HISTORY_SIZE = 10000;
/** Metrics history time. */
private int metricsHistSize = DFLT_METRICS_HISTORY_SIZE;
BTW, I picked a random example and it already has a copy-paste mistake in
the javadoc, which is there for years. I think that indicates it has no
real value and developers just do it to comply with the rule.
Some say mandatory javadoc is for the discipline but I think Apache Ignite
developers are mature enough to understand when additional documentation is
really required.
пн, 19 апр. 2021 г. в 16:37, Ivan Pavlukhin <vololo...@gmail.com>:
> Hi Andrey and Igniters,
>
> Sorry if I misread something but I have totally different opinion in
> one aspect. In my mind it is much better in practice to follow strict
> rules for public API javadocs but not for internals. I would use
> static checks for API packages and disable them for internal ones and
> refine code readability during code review. Main motivation here is
> that ubiquitous javadocs did not work well in ignite-2 and I believe
> it would not in ignite-3.
>
> 2021-04-19 13:30 GMT+03:00, Andrey Mashenkov <andrey.mashen...@gmail.com>:
> > 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
> >
>
>
> --
>
> Best regards,
> Ivan Pavlukhin
>
--
Best regards,
Alexey
