On Wed, 5 Aug 2026 13:03:21 GMT, Nir Lisker <[email protected]> wrote:
>> modules/javafx.base/src/main/java/javafx/util/converter/DateTimeStringConverter.java >> line 35: >> >>> 33: >>> 34: /// A `StringConverter` implementation for [Date] values that represent >>> dates and times. Instances of this class are >>> 35: /// immutable unless create with the >>> [#DateTimeStringConverter(DateFormat)] constructor (with a non-`null` >>> argument). >> >> "create" --> "created". >> >> Also, since the immutability exception applies to subclasses, and the note >> isn't propagated to the API docs of those subclasses, do you think it is >> worth saying that explicitly (e.g., "Instances of this class or a >> subclass...")? I'm not sure it is, but wanted to at least ask the question. > > I wasn't sure either about the subtypes. I had 3 options: to keep the implied > effect (instances of subclasses are also instances of this class, so the > description holds), to write "or of subclasses" as you mentioned, or to > explicitly write it in the subclasses class docs. Generally, when you read > the docs of a class you also need to read the docs of its superclass, > otherwise there will be a lot of repetition, so I opted for the first option. > Here the scope is small, so I don't mind mentioning it explicitly. I think what you have is fine for the reason you mention. Further, it seems unlikely that someone would read the class docs of the base class (most distant ancestor), see the immutability note there, not read the immediate superclass, and get confused because they didn't. ------------- PR Review Comment: https://git.openjdk.org/jfx/pull/1880#discussion_r3723100884
