More opportunistic documentation cleanups in the org.opengis.style …

…package.

There is no code change except the addition of a `ContrastMethod.GAMMA` value.
The amount of interfaces to keep or to delete (for replacement by newer standards)
has not yet been determined.

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

@@ -25,22 +25,14 @@
 
 
 /**
- * The ContrastEnhancement element defines contrast enhancement for a channel of a
- * false-color image or for a color image.
- *
+ * Contrast enhancement for an image channel.
  * 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 dimmest color is stretched to black
- * and the brightest color is stretched to white, with all colors in between stretched out
- * linearly. “Histogram” means to stretch the contrast based on a histogram of how many
- * colors are at each brightness level on input, with the goal of producing equal number of
- * pixels in the image at each brightness level on output. This has the effect of revealing
- * many subtle ground features.
  *
  * @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)
  */
-@XmlElement("ContrastEnchancement:type")
+@XmlElement("ContrastEnchancement")
 public final class ContrastMethod extends CodeList<ContrastMethod> {
     /**
      * Serial number for compatibility with different versions.
@@ -51,29 +43,33 @@ public final class ContrastMethod extends CodeList<ContrastMethod> {
      * List of all enumerations of this type.
      * Must be declared before any enum declaration.
      */
-    private static final List<ContrastMethod> VALUES = new ArrayList<ContrastMethod>(3);
+    private static final List<ContrastMethod> VALUES = new ArrayList<>(4);
 
     /**
-     * Normalize enchancement.
-     * “Normalize” means to stretch the contrast so that the dimmest color is stretched to black
-     * and the brightest color is stretched to white, with all colors in between stretched out
-     * linearly.
+     * Dimmest color is stretched to black and the brightest color is stretched to white.
+     * All colors in between are stretched out linearly.
      */
     @XmlElement("Normalize")
     public static final ContrastMethod NORMALIZE = new ContrastMethod("NORMALIZE");
 
     /**
-     * Histogram enchancement.
-     * “Histogram” means to stretch the contrast based on a histogram of how many
-     * colors are at each brightness level on input, with the goal of producing equal number of
-     * pixels in the image at each brightness level on output.
+     * Contrast based on a histogram of how many colors are at each brightness level on input.
+     * The goal is to produce equal number of pixels in the image at each brightness level on output.
+     * This has the effect of revealing many subtle ground features.
      */
     @XmlElement("Histogram")
     public static final ContrastMethod HISTOGRAM = new ContrastMethod("HISTOGRAM");
 
     /**
-     * No enchancement.
-     * this is the default value.
+     * Contrast based on a gamma value.
+     * A gamma value tells how much to brighten (value greater than 1)
+     * or dim (value less than 1) an image, with 1 meaning no change.
+     */
+    public static final ContrastMethod GAMMA = new ContrastMethod("GAMMA");
+
+    /**
+     * No enhancement.
+     * This is the default value.
      */
     public static final ContrastMethod NONE = new ContrastMethod("NONE");
 

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

@@ -24,8 +24,13 @@
 /**
  * The Displacement gives the X and Y displacements from the original geometry. This
  * element may be used to avoid over-plotting of multiple PolygonSymbolizers for one
- * geometry or supplying "shadows" of polygon gemeotries. The displacements are in units
- * of pixels above and to the right of the point. The default displacement is X=0, Y=0.
+ * geometry or supplying "shadows" of polygon gemeotries.
+ * The displacements units depend on the context:
+ * in {@linkplain Symbolizer#getUnitOfMeasure() symbolizer unit of measurements}
+ * when the displacement is applied by a {@link PolygonSymbolizer},
+ * but in pixels when the displacement is applied by a {@link TextSymbolizer}.
+ * The displacements are to the right of the point.
+ * The default displacement is X=0, Y=0.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium

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

@@ -24,7 +24,7 @@
 
 
 /**
- * The Font element identifies a font of a certain family, style, and size.
+ * Identification of a font of a certain family, style, and size.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
@@ -49,28 +49,29 @@ public interface Font {
     List<Expression> getFamily();
 
     /**
-     * The "font-style" SvgParameter element gives the style to use for a font. The allowed
-     * values are "normal", "italic", and "oblique".
+     * The "font-style" SvgParameter element gives the style to use for a font.
+     * The allowed values are "normal", "italic", and "oblique".
      * If null, the default is "normal".
+     *
      * @return Expression or Expression.NIL
      */
     @XmlParameter("font-style")
     Expression getStyle();
 
     /**
-     * The "font-weight" SvgParameter element gives the amount of weight or boldness to use
-     * for a font. Allowed values are "normal" and "bold".
+     * The "font-weight" SvgParameter element gives the amount of weight or boldness to use for a font.
+     * Allowed values are "normal" and "bold".
      * If null, the default is "normal".
      *
-     * @return Expression or or Expression.NIL
+     * @return Expression or Expression.NIL
      */
     @XmlParameter("font-weight")
     Expression getWeight();
 
     /**
-     * The "font-size" SvgParameter element gives the size to use for the font in pixels. The
-     * default is defined to be 10 pixels, though various systems may have restrictions on what
-     * sizes are available.
+     * The "font-size" SvgParameter element gives the size to use for the font in pixels.
+     * The default is defined to be 10 pixels, though various systems may have restrictions
+     * on what sizes are available.
      *
      * @return Expression or null
      */

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

@@ -24,10 +24,11 @@
 
 
 /**
- * A Graphic is a "graphic symbol" with an inherent shape, color(s), and possibly size. A
- * "graphic" can be very informally defined as "a little picture" and can be of either a raster
- * or vector-graphic source type. The term "graphic" is used since the term "symbol" is
- * similar to "Symbolizer" which is used in a different context in SE.
+ * A "graphic symbol" with an inherent shape, color(s), and possibly size.
+ * A "graphic" can be very informally defined as "a little picture"
+ * and can be of either a raster or vector-graphic source type.
+ * The term "graphic" is used since the term "symbol" is similar to "Symbolizer"
+ * which is used in a different context in SE.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
@@ -38,8 +39,14 @@
 public interface Graphic {
     /**
      * Returns the list of external image files or marks that comprise this graphic.
-     * All elements of the list must be instances of either {@link Mark} or {@link ExternalGraphic}.
-     * <p>
+     * All elements of the list shall be instances of either {@link Mark} or {@link ExternalGraphic}.
+     * Multiple external URLs and marks may be referenced with the semantic that they all provide
+     * the equivalent graphic in different formats.
+     *
+     * <p>If the list is empty, it is to be treated as a single default mark.
+     * That default is a square with with a 50%-gray fill and a black outline,
+     * with a size of 6 pixels, unless an explicit {@linkplain #getSize() size} is specified.</p>
+     *
      * @return List of Marks or ExternalGraphics; if empty it is to be treated a single default Mark.
      */
     @XmlElement("ExternalGraphic,Mark")
@@ -53,14 +60,16 @@ public interface Graphic {
      * Indicates the level of translucency as a floating point number whose value is between 0.0
      * and 1.0 (inclusive).  A value of zero means completely transparent.  A value of 1.0 means
      * completely opaque.  If null, the default value is 1.0, totally opaque.
+     *
+     * @return the level of translucency as a floating point number between 0 and 1 (inclusive).
      */
     @XmlParameter("stroke-opacity")
     Expression getOpacity();
 
     /**
-     * The Size element gives the absolute size of the graphic in uoms encoded as a floating-
-     * point number. The default size for an object is context-dependent. Negative values are
-     * not allowed.
+     * The Size element gives the absolute size of the graphic in uoms encoded as a floating-point number.
+     * The default size for an object is context-dependent. Negative values are not allowed.
+     *
      * The default size of an image format (such as GIF) is the inherent size of the image. The
      * default size of a format without an inherent size (such as SVG which are not specially
      * marked) is defined to be 16 pixels in height and the corresponding aspect in width. If a
@@ -69,6 +78,8 @@ public interface Graphic {
      * for image graphics to be on the order of 200 pixels in linear size and to be scaled to lower
      * sizes. On systems that can resample these graphic images "smoothly," the results will be
      * visually pleasing.
+     *
+     * @return absolute size of the graphic as a floating point number, or {@code null} for the default value.
      */
     @XmlParameter("Size")
     Expression getSize();
@@ -89,9 +100,8 @@ public interface Graphic {
     Expression getRotation();
 
     /**
-     * The AnchorPoint element of a PointSymbolizer gives the location inside of a Graphic
-     * (or label - see 11.4.4) to use for anchoring the graphic to the main-geometry point. The
-     * coordinates are given as two floating-point numbers in the AnchorPointX and
+     * Returns the location inside of a graphic to use for anchoring the graphic to the main-geometry point.
+     * The coordinates are given as two floating-point numbers in the AnchorPointX and
      * AnchorPointY elements each with values between 0.0 and 1.0 inclusive. The bounding
      * box of the graphic/label to be rendered is considered to be in a coordinate space from 0.0
      * (lower-left corner) to 1.0 (upper-right corner), and the anchor position is specified as a
@@ -105,13 +115,15 @@ public interface Graphic {
     AnchorPoint getAnchorPoint();
 
     /**
-     * The Displacement gives the X and Y displacements from the "hot-spot" point. This
-     * element may be used to avoid over-plotting of multiple graphic symbols used as part of
+     * The Displacement gives the X and Y displacements from the "hot-spot" point.
+     * This element may be used to avoid over-plotting of multiple graphic symbols used as part of
      * the same point symbol. The displacements are in units of measure above and to the right
      * of the point. The default displacement is X=0, Y=0.
      *
      * If Displacement is used in conjunction with Size and/or Rotation then the graphic
      * symbol shall be scaled and/or rotated before it is displaced.s
+     *
+     * @return displacement from the "hot-spot" point.
      */
     @XmlParameter("Displacement")
     Displacement getDisplacement();

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

@@ -21,18 +21,17 @@
 
 
 /**
- * A GraphicFill is a simple interface with only a graphic but
- * additional parameters for the GraphicFill may be provided in the
+ * Stipple-fill repeated graphic.
+ * Graphic and additional parameters for the {@code GraphicFill} may be provided in the
  * future to provide more control the exact style of filling.
  * We keep this class to reduce future code changes.
  *
- *
  * @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)
  */
 @XmlElement("GraphicFill")
-public interface GraphicFill extends Graphic{
+public interface GraphicFill extends Graphic {
     /**
      * Calls the visit method of a StyleVisitor
      *

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

@@ -29,7 +29,7 @@
  * @author Johann Sorel (Geomatys)
  */
 @XmlElement("LegendGraphic")
-public interface GraphicLegend extends Graphic{
+public interface GraphicLegend extends Graphic {
     /**
      * calls the visit method of a StyleVisitor
      *

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

@@ -22,8 +22,7 @@
 
 
 /**
- * The GraphicStroke element both indicates that a repeated-linear-graphic stroke type will
- * be used.
+ * Repeated-linear-graphic stroke.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
@@ -32,14 +31,13 @@
 @XmlElement("GraphicStroke")
 public interface GraphicStroke extends Graphic{
     /**
-     * InitialGap specifies how far away the first graphic will be drawn relative to the start of
-     * the rendering line
+     * How far away the first graphic will be drawn relative to the start of the rendering line.
      */
     @XmlElement("InitialGap")
     Expression getInitialGap();
 
     /**
-     * Gap gives the distance between two graphics.
+     * Distance between two graphics.
      */
     @XmlElement("Gap")
     Expression getGap();

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

@@ -21,8 +21,7 @@
 
 
 /**
- * The LabelPlacement element is used to position a label relative to a point, line string or
- * polygon.
+ * Position of a label relative to a point, line string or polygon.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium

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

@@ -22,8 +22,7 @@
 
 
 /**
- * The "LinePlacement" specifies where and how a text label should be rendered
- * relative to a line.
+ * Instructions about where and how a text label should be rendered relative to a line.
  *
  * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
  * @author Open Geospatial Consortium
@@ -36,8 +35,8 @@ public interface LinePlacement extends LabelPlacement {
      * The PerpendicularOffset element of a LinePlacement gives the perpendicular distance
      * away from a line to draw a label.
      *
-     * The distance is in uoms and is positive to the left-hand side of the line string. Negative
-     * numbers mean right. The default offset is 0.
+     * The distance is in uoms and is positive to the left-hand side of the line string.
+     * Negative numbers mean right. The default offset is 0.
      */
     @XmlElement("PerpendicularOffset")
     Expression getPerpendicularOffset();

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

@@ -32,21 +32,25 @@
 @XmlElement("LineSymbolizer")
 public interface LineSymbolizer extends Symbolizer {
     /**
-     * Returns the object containing all the information necessary to draw
-     * styled lines.
-     * @return Stroke object, contain information about how to draw lines
+     * Returns the object containing all the information necessary to draw styled lines.
+     *
+     * @return information about how to draw lines.
      */
     @XmlElement("Stroke")
     Stroke getStroke();
 
     /**
-     * PerpendicularOffset allows to draw lines in parallel to the original geometry. For
-     * complex line strings these parallel lines have to be constructed so that the distance
-     * between original geometry and drawn line stays equal. This construction can result in
-     * drawn lines that are actually smaller or longer than the original geometry.
+     * A distance to apply for drawing lines in parallel to the original geometry.
+     * These parallel lines have to be constructed so that the distance between
+     * original geometry and drawn line stays equal.
+     * This construction may result in drawn lines that are
+     * actually smaller or longer than the original geometry.
+     *
+     * <p>The distance units of measurement is given by {@link #getUnitOfMeasure()}.
+     * The value is positive to the left-hand side of the line string.
+     * Negative numbers mean right. The default offset is 0.</p>
      *
-     * The distance is in uoms and is positive to the left-hand side of the line string. Negative
-     * numbers mean right. The default offset is 0.
+     * @return distance to apply for drawing lines in parallel to the original geometry.
      */
     @XmlElement("PerpendicularOffset")
     Expression getPerpendicularOffset();

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

@@ -21,25 +21,37 @@
 
 
 /**
- * The OverlapBehavior element tells a system how to behave when multiple
- * raster images in a layer  overlap each other, for example with
- * satellite-image scenes. LATEST_ON_TOP and EARLIEST_ON_TOP refer to the
- * time the scene was captured.   AVERAGE means to average multiple scenes
- * together.   This can produce blurry results if the source images are
- * not perfectly aligned in their geo-referencing. RANDOM means to select
- * an image (or piece thereof) randomly and place it on top.  This can
- * produce crisper  results than AVERAGE potentially more efficiently than
- * LATEST_ON_TOP or EARLIEST_ON_TOP.   The default behaviour is
- * system-dependent.
+ * Behavior when multiple raster images in a layer overlap each other.
+ * Overlaps happen for example with satellite-image scenes.
+ * The default behavior is system-dependent.
  *
  * @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)
  */
 @XmlElement("OverlapBehavior")
 public enum OverlapBehavior {
+    /**
+     * Most recently captured scene on top.
+     */
     LATEST_ON_TOP,
+
+    /**
+     * Less recently captures scene on top.
+     */
     EARLIEST_ON_TOP,
+
+    /**
+     * Average multiple scenes together.
+     * This can produce blurry results if the source images
+     * are not perfectly aligned in their georeferencing.
+     */
     AVERAGE,
+
+    /**
+     * Select an image (or piece thereof) randomly and place it on top.
+     * This can produce crisper results than {@link #AVERAGE} but is potentially
+     * more efficiently than {@link #LATEST_ON_TOP} or {@link #EARLIEST_ON_TOP}.
+     */
     RANDOM
 }