Document better the mapping of DQM_Description to unified parameter…

… API.

Related to #78 but not yet a resolution
(whether `Description` should extend `InternationalString` is still an open question).

geoapi/src/main/java/org/opengis/metadata/quality/Description.java

@@ -41,6 +41,7 @@
 
 /**
  * Data quality measure description.
+ * A description contains a mandatory text and an optional illustration.
  *
  * @author  Alexis Gaillard (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)

geoapi/src/main/java/org/opengis/metadata/quality/Parameter.html

@@ -36,10 +36,11 @@ <h1>DQM_Parameter replacement</h1>
       <tr><td><code>valueStructure</code></td> <td>See replacement listed below</td> <td></td></tr>
     </table>
 
-    <p>The <code>Description</code> type had only two properties:</p>
+    <p>The <code>Description</code> type has two properties:</p>
     <ul>
       <li><code>textDescription</code> which is mapped to <code>getDescription()</code> (same type),</li>
-      <li><code>extendedDescription</code> (a <code>BrowseGraphic</code>) which currently has no replacement.</li>
+      <li><code>extendedDescription</code> (a <code>BrowseGraphic</code>) which currently has no replacement.<br>
+          See <a href="https://github.com/opengeospatial/geoapi/issues/78">GitHub issue #78: Should <code>Description</code> extends <code>InternationalString</code>?</a></li>
     </ul>
     <p>See <a href="https://github.com/opengeospatial/geoapi/issues/74">GitHub issue #74: Harmonize ISO 19157 parameter class</a>.</p>
 

geoapi/src/main/java/org/opengis/parameter/package-info.java

@@ -107,8 +107,8 @@
  * <h2>Data quality measure parameters</h2>
  * <p>The data quality standard uses a simple parameter class ({@code DQM_Parameter}) with only {@code name},
  * {@code definition}, {@code description}, {@code valueType}, and {@code valueStructure} properties.
- * However, in order to provide a unified parameter API, GeoAPI omits the metadata parameter class
- * and instead defines a mapping from metadata properties to GeoAPI properties.
+ * However, in order to provide a unified parameter API, GeoAPI omits the data quality parameter class
+ * and instead defines a mapping from data quality properties to GeoAPI properties.
  * The mapping is documented in {@link org.opengis.metadata.quality.Measure#getParameters()}
  * and in {@link org.opengis.parameter.GeneralParameterDescriptor} javadoc.</p>
  *

src/main/asciidoc/informative/parameters.adoc

@@ -13,27 +13,30 @@ GeoAPI provides a unified parameter framework in the `org.opengis.parameter` Jav
 The ISO 19111 model is adopted as the basis because it provides a clear separation between
 the definition of a parameter (name, aliases, identifier, expected value type and units)
 and the actual parameter value.
-Features defined by other standards and not present in ISO 19111 are retrofitted
-in the GeoAPI parameter framework.
+The parameter properties that are defined by other standards but not present
+in `CC_OperationParameter` are retrofitted in the GeoAPI parameter framework.
 
 .Main parameter properties and their mapping to ISO standards
 [.compact, options="header"]
 |==========================================================================================================
 |GeoAPI             |ISO 19111       |ISO 19115       |ISO 19157     |Remarks
 |`name`             |`name`          |`name`          |`name`        |
 |`alias`            |`alias`         |                |              |
-|`identifier`       |`identifier`    |                |              |Optional, contrarily to name which is mandatory.
-|`name.description` |                |                |`definition`  |
-|`description`      |                |`description`   |`description` |
+|`identifier`       |`identifier`    |                |              |Optional, contrarily to `name` which is mandatory.
+|`name.description` |                |                |`definition`  |Should be a short sentence.
+|`description`      |                |`description`   |`description` |`BrowseGraphic` property not explicitly supported.
 |`remarks`          |`remarks`       |                |              |
 |`valueType`        |                |                |`valueType`   |
 |`direction`        |                |`direction`     |              |
 |`minimumOccurs`    |`minimumOccurs` |`optionality`   |              |`optionality   = (minimumOccurs > 0)`
 |`maximumOccurs`    |`maximumOccurs` |`repeatability` |              |`repeatability = (maximumOccurs > 1)`
 |==========================================================================================================
 
-The result is a parameter framework richer than the parameter class defined by any of above standards taken individually.
-For example ISO 19157:2013 do not provide aliases, while some aliases are used in
+ISO 19157 `Description` type contains a mandatory text and an optional illustration.
+Only the text description is explicitly stored in the GeoAPI unified parameter type.
+However, if needed implementations can associate the `description` property to an
+object that implement both the `InternationalString` and `Description` interfaces.
+
 
 
 [[parameter_departures]]