[QUANTITY] doc consistency
jcm at head.cfa.harvard.edu
Fri May 14 11:44:42 PDT 2004
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.
One general point on optional things: What do we MEAN by "optional"?
- 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.
- 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*.
But when you distinguish between "UCD - Optional" and "Units - required, but
default is <unitless>", I don't think that is a meaningful distinction.
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
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.
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
Units: getUnit() may return the special Unit value <unitless>.
This is the default if the tag is omitted or given a blank value
Do you agree?
PS Apologies to Brian, you are quite right that I had earlier
conceded BQ has accuracy, I had forgotten that and fell into
the trap I've been angry at other people for doing, namely
going by my own instinct for truth and beauty instead of
checking the doc to remind myself what I agreed on.
More information about the dm