[QUANTITY] doc consistency

[Pierre Didelon]

Hi Jonathan,

I agree.
Some precision and details points, below in text.
I think that more precision and explanations  are needed in the doc,
concerning these default values, and the possible (authorised?)
corresponding serialisation.

Pierre

Jonathan McDowell wrote:
> Pierre
>  Thanks for your initial and very helpful editorial comments on Q.
>  I have tried to address some of them in a slightly
>  different new version V0.22. (mainly changed in sections 5 and 6.2.
>  It's just a beginning, and I haven't dealt with the serialization questions,
>  but let me know if it is the right direction.
> 
>  http://hea-www.harvard.edu/~jcm/www/vo/docs/qty22.pdf

->http://hea-www.harvard.edu/~jcm/vo/docs/qty22.pdf
comment later on.
> 
>  
>  One general point on optional things: What do we MEAN by "optional"?

Mainly that tag can be omitted in serialisation if "default values",
most oftently null ones  meaning that the corrsponding piece of information
is unknown, is value available fot the tag.
> 
>   - for each "get" method giving data you can extract from an object,
>     (I avoid the words 'for each attribute' since we are talking interfaces)
>     there may or may not be a special `null' return value (empty list, unitless tag,
>     NaN value, etc.
> 
>   - for a given serialization, there may be default values for some
>     tags, so that if that tag is omitted from the serialization, 
>     the corresponding behaviour of the object is as if the default
>     value had been given. Note that in principle different
>     serializations don't have to allow the same things to be defaulted.
But a workable serailisation has to be proposed for interop?
> 
>   - for a given constructor method for the object, the same is
>     true: some things may have default values - but a different
>     constructor method might have different defaults.
> 
>  I like the idea of most things being optional (in the sense of having
>  defaults) in the *serializations*. 

Yes, and for "common" or "simple" behavior, quantity objects can be very small
when serialised.
> 
>  But when you distinguish between "UCD - Optional" and "Units - required, but
>  default is <unitless>", I don't think that is a meaningful distinction.

The only distinction is that unknown UCD is "translated" in serialisation
with the non-appearance of a tag related to UCD, perhaps like unknow units,
while number without units is "translated" in serialisation by <unitless>,
which may be better expressed by <units>NONE</units>, or whatever value of the
unit tag, and not by a special tag.
Or value without units are forbidden in VO framework?

>  I don't think it makes sense to talk about things being default
>  in the *objects* or the *interface*, and you have to be very careful
>  when talking about things being 'optional'. Instead, it makes sense to
>  talk about whether there is a concept of a null or special value
>  that means 'information not available'.
> 
>  Everything is "required" in the special sense that you can always ask
>  the question "what is your UCD?" "what is your unit?", "what is  your
>  accuracy?", but might get the answer "I don't have one" (ucd-less,
>  unit-less, empty accuracy list). 
> 
>  Many things are optional in the sense that if absent in the
>  serialization, their value is a special value indicating  the absence of
>  valid data. 
Then unitless which correspond to the absence of data, because it is not needed,
not due to uncomplete knowledge of the quantity object, does not match
this def of default value.
> 
>  Then there are a few things that it makes sense to provide non-trivial
>  defaults for in the serialization (e.g. data type = string). But
>  the concept of a default data type doesn't make sense in the object,
>  just in the serialization and the constructors.
Yes.
>   
>  So when you say "UCD - Optional" and "Units - required, but
>  default is <unitless>", you actually mean:
> 
>  UCD:  getUCDString() may return blank or null string to indicate
>  no associated UCD. This is the default if the tag is omitted on
>  serialization.
> 
>  Units: getUnit() may return the special Unit value <unitless>.
>  This is the default if the tag is omitted or given a blank value
>  on serialization.

 From Brian previous comment, I feel like if the tag <unitless> is
teh default but it IS required in serailisation!
But from point above it seems less clear to me.