Add a comment in org.opengis.style package saying that it was deriv…

…ed from an XML encoding and does not align with ISO 19117:2012.

This package was not part of GeoAPI 3. It is currently in geoapi-pending, but maybe it should be removed until a new style API is defined.
Various OGC working groups are working on new style API, and ISO 19117:2012 is quite different than the current interfaces.

In  this commit we only update some documentation.
A future commit may remove this package completly.

geoapi-pending/src/main/java/org/opengis/annotation/XmlElement.java

@@ -33,12 +33,15 @@
  * only provides enough information for finding the corresponding XML element in
  * the {@linkplain XmlSchema schema}.
  *
+ * <p>This annotation is used for documentation purpose only and may be removed in a future version.
+ * The reason is that GeoAPI tries to publish interfaces based on UML instead of XSD schemas.</p>
+ *
  * @author  Martin Desruisseaux (IRD)
  * @since   GeoAPI 2.0
  */
 @Documented
 @Target({TYPE,METHOD,FIELD})
-@Retention(RUNTIME)
+@Retention(SOURCE)                  // Used for documentation purpose only.
 public @interface XmlElement {
     /**
      * The name of the element in the XML schema.

geoapi-pending/src/main/java/org/opengis/annotation/XmlParameter.java

@@ -28,12 +28,15 @@
  * Maps a method to the XML parameter. This annotation can be used with reflection for
  * finding the corresponding XML parameter in the {@linkplain XmlSchema schema}.
  *
+ * <p>This annotation is used for documentation purpose only and may be removed in a future version.
+ * The reason is that GeoAPI tries to publish interfaces based on UML instead of XSD schemas.</p>
+ *
  * @author  Johann Sorel (Geomatys)
  * @since   GeoAPI 2.2
  */
 @Documented
 @Target(METHOD)
-@Retention(RUNTIME)
+@Retention(SOURCE)                  // Used for documentation purpose only.
 public @interface XmlParameter {
     /**
      * The name of the element in the XML schema.

geoapi-pending/src/main/java/org/opengis/style/AnchorPoint.java

@@ -20,6 +20,7 @@
 import org.opengis.annotation.XmlElement;
 import org.opengis.filter.Expression;
 
+
 /**
  * An AnchorPoint identifies the location inside a textlabel to use as an
  * "anchor" for positioning it relative to a point geometry.
@@ -28,11 +29,9 @@
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
  * @author Ian Turton
- * @since GeoAPI 2.2
  */
 @XmlElement("AnchorPoint")
 public interface AnchorPoint {
-
     /**
      * get the x coordinate of the anchor point
      *
@@ -55,5 +54,4 @@ public interface AnchorPoint {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }

geoapi-pending/src/main/java/org/opengis/style/ChannelSelection.java

@@ -29,11 +29,9 @@
  * @author Open Geospatial Consortium
  * @author Ian Turton, CCG
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("ChannelSelection")
 public interface ChannelSelection {
-
     /**
      * get the RGB channels to be used
      *

geoapi-pending/src/main/java/org/opengis/style/ColorMap.java

@@ -22,10 +22,8 @@
 
 
 /**
- * <p>The ColorMap element defines the mapping of palette-type raster colors or fixed-
- * numeric pixel values to colors using an Interpolate or Categorize SE function
- * </p>
- * <p>
+ * The ColorMap element defines the mapping of palette-type raster colors or fixed-
+ * numeric pixel values to colors using an Interpolate or Categorize SE function.
  * For example, a DEM raster giving elevations in meters above sea level can be
  * translated to a colored  image with a ColorMap.  The quantity attributes of
  * a color-map are used for translating between numeric  matrixes and color
@@ -35,15 +33,13 @@
  * may be used in the future to match character values.   Not all systems can
  * support opacity in colormaps.  The default opacity is 1.0 (fully opaque).
  * Defaults for quantity and label are system-dependent.
- * </p>
+ *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("ColorMap")
 public interface ColorMap {
-
     /**
      *
      * @return Interpolate or Categorize function
@@ -56,5 +52,4 @@ public interface ColorMap {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }

geoapi-pending/src/main/java/org/opengis/style/ColorReplacement.java

@@ -20,6 +20,7 @@
 import org.opengis.annotation.XmlElement;
 import org.opengis.filter.Expression;
 
+
 /**
  * The ColorReplacement element, which may occur multiple times, allows to replace a
  * color in the ExternalGraphic, the color specified in the OriginalColor sub-element, by
@@ -28,11 +29,9 @@
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("ColorReplacement")
 public interface ColorReplacement {
-
     /**
      * Recoding: Transformation of discrete values to any other values. This is needed
      * when integers have to be translated into text or, reversely, text contents into other
@@ -50,5 +49,4 @@ public interface ColorReplacement {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }

geoapi-pending/src/main/java/org/opengis/style/ContrastEnhancement.java

@@ -22,9 +22,8 @@
 
 
 /**
- * <p>The ContrastEnhancement object defines contrast enhancement for a channel of
+ * The ContrastEnhancement object defines contrast enhancement for a channel of
  * a false-color image or for a color image.
- * </p>
  *
  * <p>In the case of a color image, the relative grayscale brightness of a pixel
  * color is used. ?Normalize? means to stretch the contrast so that the
@@ -44,11 +43,9 @@
  * @author Open Geospatial Consortium
  * @author Ian Turton, CCG
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("ContrastEnhancement")
 public interface ContrastEnhancement {
-
     /**
      * We use a codeList to enable more enchancement type possibilities.
      */
@@ -71,5 +68,4 @@ public interface ContrastEnhancement {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }

geoapi-pending/src/main/java/org/opengis/style/ContrastMethod.java

@@ -39,7 +39,6 @@
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("ContrastEnchancement:type")
 public final class ContrastMethod extends CodeList<ContrastMethod> {

geoapi-pending/src/main/java/org/opengis/style/Description.java

@@ -20,23 +20,26 @@
 import org.opengis.annotation.XmlElement;
 import org.opengis.util.InternationalString;
 
+
 /**
- * A Description is used to store various informations
- * who describe an element. Description values are mostly used
- * in User Interfaces (Lists, trees, ...).
+ * Informative description of a style object being defined.
+ * Description values are mostly used in User Interfaces (Lists, trees, ...).
+ *
+ * <p>Note that most style object also have a name.
+ * But the name is not part of the description because a name
+ * has a functional use that is more than just descriptive.</p>
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 @XmlElement("Description")
 public interface Description {
-
     /**
-     * Returns the human readable title of this style.
+     * Returns the human readable title of the style.
      * This can be any string, but should be fairly short as it is intended to
      * be used in list boxes or drop down menus or other selection interfaces.
+     *
      * @return the human readable title of this style.
      */
     @XmlElement("Title")
@@ -45,6 +48,7 @@ public interface Description {
     /**
      * Returns a human readable, prose description of this style.
      * This can be any string and can consist of any amount of text.
+     *
      * @return a human readable, prose description of this style.
      */
     @XmlElement("Abstract")
@@ -56,6 +60,4 @@ public interface Description {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }
-

geoapi-pending/src/main/java/org/opengis/style/Displacement.java

@@ -31,7 +31,6 @@
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
  * @author Ian Turton, CCG
- * @since GeoAPI 2.2
  */
 @XmlElement("Displacement")
 public interface Displacement {

geoapi-pending/src/main/java/org/opengis/style/ExtensionSymbolizer.java

@@ -20,20 +20,19 @@
 import java.util.Map;
 import org.opengis.filter.Expression;
 
+
 /**
  * An symbolizer interface for all unnormalized symbolizers,
  * This interface should be used for vendor specific symbolizers.
  *
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.3
  */
 public interface ExtensionSymbolizer extends Symbolizer {
-
     /**
-     * Returns the name of the extension, this name should be commun to all 
+     * Returns the name of the extension, this name should be commun to all
      * implementation of a given extension symbolizer sub class.
-     * 
+     *
      * @return the symbolizer extension name
      */
     String getExtensionName();
@@ -52,5 +51,4 @@ public interface ExtensionSymbolizer extends Symbolizer {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }

geoapi-pending/src/main/java/org/opengis/style/ExternalGraphic.java

@@ -30,7 +30,6 @@
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
  * @author Chris Dillard (SYS Technologies)
- * @since GeoAPI 2.2
  */
 @XmlElement("ExternalGraphic")
 public interface ExternalGraphic extends GraphicalSymbol {

geoapi-pending/src/main/java/org/opengis/style/ExternalMark.java

@@ -21,6 +21,7 @@
 import org.opengis.annotation.XmlElement;
 import org.opengis.metadata.citation.OnlineResource;
 
+
 /**
  * The alternative to a WellKnownName is an external mark format. The MarkIndex
  * allows an individual mark in a mark archive to be selected. An example format for an
@@ -30,10 +31,8 @@
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
  * @author Johann Sorel (Geomatys)
- * @since GeoAPI 2.2
  */
 public interface ExternalMark {
-
     /**
      * Returns on online resource defined by a URI.
      *
@@ -77,5 +76,4 @@ public interface ExternalMark {
      * @param visitor the style visitor
      */
     Object accept(StyleVisitor visitor, Object extraData);
-
 }