Remarks on javadoc in JSR-363 Unit-API

Skip to first unread message

Martin Desruisseaux

Apr 10, 2017, 4:22:02 AM4/10/17
to Units Developers

Hello all

Below are some remarks about JSR-363 Javadoc. They are observations that I had while implementing the interfaces. All those remarks are only about Javadoc, except the last one which could have an impact on the API.


Javadoc said "Return a factory for this Quantity". I think that we mean "Returns a factory for the given Quantity type". Also the javadoc for the @param tag should be "the quantity type".


Javadoc said "Returns the product of this Quantity divided by the Quantity specified". I guess that we mean "Returns the quotient ...".


Javadoc for @return tag said "the given system of units". I think that we mean "the system of units for the given name".


getUnit(Class<Q> quantityType) does not said what to do if no unit is found for the given quantity type. Should the method returns null or throw an exception? My implementation currently returns null, but I could change if the group suggests otherwise.


UnitFormat.label(String) said that it throws an IllegalArgumentException for illegal symbol, but Unit.alternate(String) does not said what happen in such case. I presume that in the throws tag, the "if the specified symbol is already associated to a different unit" statement could be replaced by "if the specified symbol is not valid or is already associated to a different unit".


If we want cross-implementation interoperability, we may need to define the behavior of Dimension.equals(Object). It would be needed because two Unit instances are considered convertible if all their dimensions are equal. One possible approach would be to normalize dimension symbols (L for length, T for time, etc.) and require Dimension.equals(Object) to compare the symbols. But we could also choose that allowing mix of different Dimension implementation is not a goal, which is all-right (I just don't know if it was a conscientious decision or an accident).


The definition given in Javadoc basically restricts "linear" conversions to this formula:

y = a*x

The definition given in Converter.isLinear() does not allow the following formula, despite that formula being usually considered linear too:

y = a*x + b

So conversions between Celsius and Kelvin (or between Celsius and Fahrenheit) are not linear according the definition given in Converter.isLinear() javadoc, which I found surprising. It seems to me that the "isLinear" name is not appropriate for that method. Maybe "isScale" would have been more accurate.


Werner Keil

Apr 10, 2017, 6:43:12 AM4/10/17
to Units Developers

Thanks for the observations.

Could you either create an issue in or file a pull-request?
As EG member you could also directly push something, but it would be good to review it by a Maintenance Lead (the 3 Spec Leads now are) at this point since the JSR is Final.

Although there is no imminent plan for a MR, these kinds of things are normally done via MR, see javax.annotation, so with enough proposed changes we could think of that in the near future.

Reply all
Reply to author
0 new messages