[sis] 11/33: Documentation clarification in GridExtent.

[de...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git

commit 895a7412a6e3be7c49d973e83f1d42516f0d5cfe
Author: Martin Desruisseaux <de...@apache.org>
AuthorDate: Wed May 30 10:25:29 2018 +0000

    Documentation clarification in GridExtent.
    
    
    git-svn-id: https://svn.apache.org/repos/asf/sis/branches/JDK8@1832531 13f79535-47bb-0310-9956-ffa450edef68
---
 .../java/org/apache/sis/coverage/grid/GridExtent.java    | 16 +++++++++-------
 .../java/org/apache/sis/coverage/grid/GridGeometry.java  | 11 +++++++++++
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
index 816a62f..7810f74 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
@@ -30,14 +30,16 @@ import org.opengis.coverage.grid.GridCoordinates;
 
 /**
  * A range of grid coverage coordinates, also known as "grid envelope".
- * {@code GridExtent} instances are unmodifiable,
- * so they can be shared between different {@link GridGeometry} instances.
+ * {@code GridExtent} are defined by {@linkplain #getLow() low} coordinates (often all zeros)
+ * and {@linkplain #getHigh() high} coordinates, <strong>inclusive</strong>.
+ * For example a grid with a width of 512 cells can have a low coordinate of 0 and high coordinate of 511.
  *
- * <p><b>CAUTION:</b>
- * ISO 19123 defines {@linkplain #getHigh high} coordinates as <strong>inclusive</strong>.
- * We follow this specification for all getters methods, but developer should keep in mind
- * that this is the opposite of Java2D usage where {@link java.awt.Rectangle} maximal values are exclusive.
- * When the context is ambiguous, an explicit {@code isHighIncluded} argument is required.</p>
+ * <div class="note"><b>Note:</b>
+ * The inclusiveness of {@linkplain #getHigh() high} coordinates come from ISO 19123.
+ * We follow this specification for all getters methods, but developers should keep in mind
+ * that this is the opposite of Java2D usage where {@link java.awt.Rectangle} maximal values are exclusive.</div>
+ *
+ * {@code GridExtent} instances are unmodifiable, so they can be shared between different {@link GridGeometry} instances.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @version 1.0
diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
index 79ac7cc..d719a23 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
@@ -110,6 +110,9 @@ public class GridGeometry implements Serializable {
      * The valid domain of a grid coverage, or {@code null} if unknown. The lowest valid grid coordinate is zero
      * for {@link java.awt.image.BufferedImage}, but may be non-zero for arbitrary {@link RenderedImage}.
      * A grid with 512 cells can have a minimum coordinate of 0 and maximum of 511.
+     *
+     * @see #EXTENT
+     * @see #getExtent()
      */
     protected final GridExtent extent;
 
@@ -117,6 +120,9 @@ public class GridGeometry implements Serializable {
      * The geodetic envelope, or {@code null} if unknown. If non-null, this envelope is usually the grid {@link #extent}
      * {@linkplain #gridToCRS transformed} to real world coordinates. The Coordinate Reference System} (CRS) of this
      * envelope defines the "real world" CRS of this grid geometry.
+     *
+     * @see #ENVELOPE
+     * @see #getEnvelope()
      */
     protected final ImmutableEnvelope envelope;
 
@@ -129,6 +135,9 @@ public class GridGeometry implements Serializable {
      *     DirectPosition aCellIndices = ...:
      *     DirectPosition aPixelCenter = gridToCRS.transform(pixels, aCellIndices);
      * }
+     *
+     * @see #CRS
+     * @see #getGridToCRS()
      */
     protected final MathTransform gridToCRS;
 
@@ -144,6 +153,8 @@ public class GridGeometry implements Serializable {
     /**
      * The resolution in units of the CRS axes.
      * Computed only when first needed.
+     *
+     * @see #resolution(boolean)
      */
     private transient double[] resolution;