Remarks on javadoc in JSR-363 Unit-API
Martin Desruisseaux
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.
ServiceProvider.getQuantityFactory(Class)
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".
Quantity.divide(Quantity)
Javadoc said "Returns the product of this Quantity divided by the Quantity specified". I guess that we mean "Returns the quotient ...".
SystemOfUnitsService.getSystemOfUnits(String)
Javadoc for @return tag said "the given system of units". I think that we mean "the system of units for the given name".
SystemOfUnit.getUnit(Class)
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.
Unit.alternate(String)
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".
Dimension
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).
Converter.isLinear()
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.
