What about Unit.annotate()?

[keilw]

At the moment the Unit interface defines alternate() or transform() methods but annotate() is only exposed via the AbstractUnit base class of implementations. Unless it is too little-used and this is meant to be a status-quo, could it also be added to the Unit interface from a future version?

[desruisseaux]

It depends: what is the purpose of annotate?

[keilw]

To create an "annotated unit", but unlike alternate, compound (aka mix) or transform, annotate wasn't in JSR 275 either: https://www.jscience.org/api/javax/measure/unit/Unit.html

Seems it is for http://ceur-ws.org/Vol-432/owled2008eu_submission_21.pdf or the "curly braces" in UCUM: http://unitsofmeasure.org/ucum.html It seems more specific than the others.

[desruisseaux]

Okay, I have read §6 curly braces section on UCUM page. Now how do we translate that in Java API? Can you post a javadoc describing the contract of such annotate method? Is the only effect of that method is to modify the String representation of the unit? Do we provide a method for fetching the annotation set by annotate? What happen to the annotation in arithmetic expression? For example if A were annotated, is the annotation gone after A.multiply(B)?

[keilw]

@dautelle It seems annotate() is very specific to the UCUM catalog, or did it have any more general purpose?

[dautelle]

Annotations can be used to be more specific about the unit, for exemple 15.0 Gal [Petroleum], mile[standard] different from a mile[US_survey], etc.
See Mapplesoft examples

[keilw]

@dautelle Could you please raise your thumb here, as nobody really seems to care about it in the API?
The point about all these decision tickets is to determine if enough people think they are important enough to provide API methods. At the moment this one would fail, given the Apache inspired voting criteria this one fails to be relevant or "interesting" enough. #185 gained 4 +1 votes, so it'll pass. #103 has 2, so one is missing. All others failed meaning there's no action on them.

[teobais]

Having read the discussion and related links, I believe annotations should better be provided in our API. That way, we will ease our users' way of working, in case they need more explanatory units. That said, +1 from my side.

[keilw]

Great, thanks a lot. @unitsofmeasurement/experts, @unitsofmeasurement/contributors, please also chip in if you agree. While discussions about implementation details of a particular implementation (resulting of either annotate() or mix(), etc.) are certainly welcome, because we also have to finish the RI soon, they are not really subject of these questions which are simply "is it important and useful enough to be in the API?".

[teobais]

Maybe we need to close this one as well, given that we closed most of the related ones today?

[keilw]

I think it's to rarely used for the API.

[teobais]

Cool! That drops the overall amount of open issues to an one-digit number again :-)