Hi Andrey,
I've update a PR [1].
* Added maven task for Javadoc style checks (public API only, for now)
* Updated DEVNOTES.
* Suppress Javadoc style errors for broken modules using Checkstyle
suppression configuration.
Unfortunately, maven plugin configuration allows to filter out
module
Hi,
Unfortunately, such things as the "many private APIs" rule can't be
formalized for any validation tool. So we have to choose between rules
like "everything should be documented" and "private API documentation
is not mandatory".
The community prefers the second approach. I don't want to argue
Hi,
In my strong opinion Javadoc is a code. Any errors in Javadoc are
equal to the bug in the code and must be treated as such. Proper and
extensive Javadoc for all public and many private APIs is absolutely
essential for this project, its growth and maturity.
I'm surprised this community still
Hi,
I think that scope should be limited by public API for beginning.
Also I don't sure that we should support specific tags like @apiNote,
@implSpec, @implNote.
Let's move using the following plan:
1. Create an empty (effectively) checkstyle config for javadoc
checking and commit it to the
I've fixed the PR.
Now,
1. Javadoc style is only checked if it is present for the element. All
declared javadoc tags MUST have a description.
So, one should either write correct javadoc or don't write at all.
2. Additional checks performed for non-internal and non-test classes. All
public and
Alexey,
These are bad examples and unfortunately, most of the Ignite code doesn't
look self-descriptive.
(Do you feel the difference between @SerializableTransient and
@TransientSerializable?)
To understand the semantic of e.g. 'metricsHistSize' you have to analyze
its usages.
Getter and setter
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
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
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
