[
https://issues.apache.org/jira/browse/SIS-91?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Martin Desruisseaux updated SIS-91:
-----------------------------------
Description:
The developer guide needs to be expanded with the following items:
* The four levels of documentation: members, types, packages, modules (APT
pages).
* Class name policy ({{Abstract}}, {{Default}}, {{General}}, {{Immutable}}).
* A note about unions (in the C/C++ sense): sometime simulated by a set of
getter methods where exactly one method can return a non-null value.
* Collections are modifiable by default. But the getter methods are not
guaranteed to return the same instance after other methods of the same instance
have been invoked, or after the metadata has been marshalled. In addition,
collection may sometime be {{null}} instead of empty if the collection is a
property of an union (see above) where an other property is defined.
* The {{castOrCopy}} methods, found in metadata, referencing, _etc_.
* Convenience constructors in metadata object. Their arguments are the
mandatory properties of the metadata object, and the argument types are often
simpler than the corresponding setter method (singleton, {{CharSequence}}
instead of {{InternationalString}}).
* Policy about {{null}} argument value: often accepted in the following
contexts:
** The value of an optional property. Very common in metadata objects.
** In static method calculating a value from the given argument, without
changing the state of any object. In such case, the value returned by that
method will often be {{null}} as well. This is very similar to {{NaN}} number
in {{java.lang.Math}} functions.
** Collections may sometime be null if the collection is a member of an union
(see above) and a value is already defined for an other type.
* Possibility to specify the reason why a metadata element is null, with
{{NilReason.createNilObject(Class)}}.
* Unified identifiers view ({{IdentifierMap}}).
* See documentation in {{sis-metadata/src/site/index.apt}} for more.
was:
The developer guide needs to be expanded with the following items:
* The four levels of documentation: members, types, packages, modules (APT
pages).
* Class name policy ({{Abstract}}, {{Default}}, {{General}}, {{Immutable}}).
* Collections are modifiable by default. But the getter methods are not
guaranteed to return the same instance after other methods of the same instance
have been invoked, or after the metadata has been marshalled.
* The {{castOrCopy}} methods, found in metadata, referencing, _etc_.
* Convenience constructors in metadata object. Their arguments are the
mandatory properties of the metadata object, and the argument types are often
simpler than the corresponding setter method (singleton, {{CharSequence}}
instead of {{InternationalString}}).
* Policy about {{null}} argument value: often accepted in the following
contexts:
** The value of an optional property. Very common in metadata objects.
** In static method calculating a value from the given argument, without
changing the state of any object. In such case, the value returned by that
method will often be {{null}} as well. This is very similar to {{NaN}} number
in {{java.lang.Math}} functions.
* Possibility to specify the reason why a metadata element is null, with
{{NilReason.createNilObject(Class)}}.
* Unified identifiers view ({{IdentifierMap}}).
* See documentation in {{sis-metadata/src/site/index.apt}} for more.
> Addition to the developer guide for metadata
> --------------------------------------------
>
> Key: SIS-91
> URL: https://issues.apache.org/jira/browse/SIS-91
> Project: Spatial Information Systems
> Issue Type: Improvement
> Components: Documentation
> Reporter: Martin Desruisseaux
> Assignee: Martin Desruisseaux
> Priority: Minor
> Fix For: 0.3
>
>
> The developer guide needs to be expanded with the following items:
> * The four levels of documentation: members, types, packages, modules (APT
> pages).
> * Class name policy ({{Abstract}}, {{Default}}, {{General}}, {{Immutable}}).
> * A note about unions (in the C/C++ sense): sometime simulated by a set of
> getter methods where exactly one method can return a non-null value.
> * Collections are modifiable by default. But the getter methods are not
> guaranteed to return the same instance after other methods of the same
> instance have been invoked, or after the metadata has been marshalled. In
> addition, collection may sometime be {{null}} instead of empty if the
> collection is a property of an union (see above) where an other property is
> defined.
> * The {{castOrCopy}} methods, found in metadata, referencing, _etc_.
> * Convenience constructors in metadata object. Their arguments are the
> mandatory properties of the metadata object, and the argument types are often
> simpler than the corresponding setter method (singleton, {{CharSequence}}
> instead of {{InternationalString}}).
> * Policy about {{null}} argument value: often accepted in the following
> contexts:
> ** The value of an optional property. Very common in metadata objects.
> ** In static method calculating a value from the given argument, without
> changing the state of any object. In such case, the value returned by that
> method will often be {{null}} as well. This is very similar to {{NaN}} number
> in {{java.lang.Math}} functions.
> ** Collections may sometime be null if the collection is a member of an union
> (see above) and a value is already defined for an other type.
> * Possibility to specify the reason why a metadata element is null, with
> {{NilReason.createNilObject(Class)}}.
> * Unified identifiers view ({{IdentifierMap}}).
> * See documentation in {{sis-metadata/src/site/index.apt}} for more.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
