Hello Rob
Thanks for your observation. Indeed, the javadoc of AttributeNames class
merely repeat documentation that exists elsewhere (ACDD and
CF-Conventions). The ACDD and CF-Convention are the authoritative
sources, so we should comply with whatever they said. The only reason
why we did not reproduced the documentation more extensively is that I
was not sure if it would be compliant with ACDD / CF-Convention
licensing. I presumed that copying a summary sentence could be
considered "fair use" but was not sure if more extensive copying would
still "fair use" under copyright laws.
However given that the ACDD and CF-Conventions authors are mostly public
or non-profit organisations, there is good chances that the copy
conditions are very permissive. It just needs to be verified.
Regards,
Martin
Le 30/05/2017 à 14:19, Rob Wallace a écrit :
> Hello
>
> Comparing 'Field Detail' in the Javadoc for the AttributeNames class
> with ACDD 1-3, in many cases, the Javadoc merely repeats the same
> description as used for its 'Field Summary'. In the ACDD, the field
> description is more fully described. See field 'COMMENT' for example:
>
> ACDD under Recommended - "Miscellaneous information about the data,
> not captured elsewhere. This attribute is defined in the CF
> Conventions (http://cfconventions.org)."
>
> Javadoc - "The "comment" attribute name for miscellaneous information
> about the data (Recommended)."
>
> I feel that semantically the two are similar in a general sense only,
> but not identical in a fuller sense of the meaning. If not identical
> semantically, it means that the ACDD document will always have to be
> referred to in order to give a fuller definition and guidance. So then
> the Javadoc is not properly the full story.
>
> I feel it is a pity to not include what could be very useful detail in
> the 'Field Detail' of the Javadoc. The Apache SIS is software used
> for scientific purposes and terms need tight definitions that improve
> people's understanding, and Javadoc is to where we all refer when
> trying to be clear about our facts. It also reduces arguments and
> misunderstanding about the detail - so important when multinational
> projects are involved.
>
> What is the development team's policy on this matter?
>
> Kind regards
>
> Rob Wallace
>
>
