Small javadoc corrections

Nir Lisker nlisker at gmail.com
Wed Jun 14 23:44:21 UTC 2017


A few more corrections for the Javadoc:

- ListChangeListener.Change<E>, in the code example, "<tem>" should be
"<Item>".

In this class refer to the following methods (I'm looking at
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide
):

- getAddedSubList: is phrased unconventionally. Instead of the usual "does
X" phrasing, it uses "to do X, use this method". So the first sentence
should probably be "Get(s) a subList view of the list that contains only
the elements added."

- getPermutation(int): similar to above. Probably "Allows to observe the
permutation that happened" or similar is slightly more in line.

- getPermutation(): "an permutation" should be "a permutation".

- wasAdded: missing a period in its first and only sentence.

- next: "a requires" should probably be "and requires".

- getTo: the return description should be "an end" instead of "a end".

- next and reset: use the unconventional imperative "Go to..." and "Reset
to..." instead of "Goes to..." and "Resets to...".

- Some methods are described by what they return rather than what they do.
getAddedSize: "Size of the interval that was added.", getRemovedSize: "Size
of getRemoved() list.", getRemoved: "An immutable list of removed/replaced
elements." etc. More conventional is "returns/gets a/an..." or similar,
although this is also

- Most methods don't use @code style when mentioning other methods (compare
getAddedSubList and wasUpdated, for example). If you follow the style guide
I linked, then many other classes are affected.

Other:

- TreeItem should have a link to TreeView in the first sentence, or as a
@see, or both. Possibly also for TreeTableView as these are its 2 main uses.


More information about the openjfx-dev mailing list