Agree with Ivan - internal code does not need mandatory Javadoc. Most of it is meaningless and does not bring any value, just wastes everyone's time.
Alexey, I think public APIs should always have Javadoc, even if it is the same thing as the member name, but with spaces - this will make the documentation nicer and easier to search. On Mon, Apr 19, 2021 at 5:21 PM Alexey Kukushkin <kukushkinale...@gmail.com> wrote: > 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 >
