RFR: 8270996: javadoc: missing comments in serialized classes

[Kevin Rushforth]

On Thu, 29 Feb 2024 16:53:26 GMT, Andy Goryachev <angorya at openjdk.org> wrote:

> Adding `@SuppressWarnings("doclint")` to Serializable classes to silence the javadoc "missing comments" warning.
> (There is no javadoc command group for serialization like doclint:missing) 
> 
> Pros:
> - the classes are fairly stable, we can ask the reviewers to pay extra attention to any javadoc changes
> 
> Cons: 
> - all javadoc warnings will be suppressed

I am not in favor of suppressing all javadoc warnings, especially at the class level. Is there no way to suppress just the serial warnings?

If we want to suppress the warnings (rather than providing actual docs for the fields, which may have little value), I think they should be moved down to the individual elements.

I'd like a second pair of eyes on this.

modules/javafx.base/src/main/java/javafx/event/Event.java line 45:

> 43:  */
> 44: @SuppressWarnings("doclint")
> 45: public class Event extends EventObject implements Cloneable {

I don't think we should suppress all warnings, especially at the class level.

-------------

Changes requested by kcr (Lead).

PR Review: https://git.openjdk.org/jfx/pull/1386#pullrequestreview-1909468036
PR Comment: https://git.openjdk.org/jfx/pull/1386#issuecomment-1971620958
PR Review Comment: https://git.openjdk.org/jfx/pull/1386#discussion_r1507936053