Replacement of "Proj.4 library" by "Proj library" and other documentation update or formatting.

There is no code change in this commit, except the addition of @Native annotation on a constant.

3 files changed, 83 insertions, 87 deletions

diff --git a/jniwrap/org/proj4/PJ.java b/jniwrap/org/proj4/PJ.java
index 6b387287..27b0f25d 100644
--- a/jniwrap/org/proj4/PJ.java
+++ b/jniwrap/org/proj4/PJ.java
@@ -1,10 +1,10 @@
 /******************************************************************************
  * Project:  PROJ.4
- * Purpose:  Java/JNI wrappers for PROJ.4 API.
+ * Purpose:  Java/JNI wrappers for PROJ API.
  * Author:   Martin Desruisseaux
  *
  ******************************************************************************
- * Copyright (c) 2011, Open Geospatial Consortium, Inc.
+ * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -23,58 +23,60 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
- *****************************************************************************
- * This file is a copy of a file developed in the GeoAPI "Proj.4 binding"
- * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is
- * modified, please consider synchronizing the changes with GeoAPI.
+ ******************************************************************************
  */
 package org.proj4;
 
+import java.util.Objects;
+import java.lang.annotation.Native;
+
 
 /**
- * Wraps the <a href="http://proj.osgeo.org/">Proj4</a> {@code PJ} native data structure.
- * Almost every methods defined in this class are native methods delegating the work to the
- * Proj.4 library. This class is the only place where such native methods are defined.
- * <p>
- * In the Proj.4 library, the {@code PJ} structure aggregates in a single place information usually
- * split in many different ISO 19111 interfaces: {@link org.opengis.referencing.datum.Ellipsoid},
+ * Wraps the <a href="http://proj4.org/">Proj</a> {@code PJ} native data structure.
+ * Almost every methods defined in this class are native methods delegating the work to the Proj library.
+ * This class is the only place where such native methods are defined.
+ *
+ * <p>In the Proj library, the {@code PJ} structure aggregates in a single place information usually
+ * splitted in many different ISO 19111 interfaces: {@link org.opengis.referencing.datum.Ellipsoid},
  * {@link org.opengis.referencing.datum.Datum}, {@link org.opengis.referencing.datum.PrimeMeridian},
  * {@link org.opengis.referencing.cs.CoordinateSystem}, {@link org.opengis.referencing.crs.CoordinateReferenceSystem}
  * and their sub-interfaces. The relationship with the GeoAPI methods is indicated in the
- * "See" tags when appropriate.
+ * "See" tags when appropriate.</p>
  *
  * @author  Martin Desruisseaux (Geomatys)
+ * @version 5.1
+ * @since   4.8
  */
 public class PJ {
     /**
-     * The maximal number of dimension accepted by the {@link #transform(PJ, int, double[], int, int)}
-     * method. This upper limit is actually somewhat arbitrary. This limit exists mostly as a safety
-     * against potential misuse.
+     * The maximal number of dimension accepted by the {@link #transform(PJ, int, double[], int, int)} method.
+     * This upper limit is actually somewhat arbitrary. This limit exists mostly as a safety against potential misuse.
      */
+    @Native
     public static final int DIMENSION_MAX = 100;
-    // IMPLEMENTATION NOTE: if the value is modified, edit also the native C file.
 
     /**
-     * Loads the Proj4 library.
+     * Loads the Proj library.
      */
     static {
         System.loadLibrary("proj");
     }
 
     /**
-     * The pointer to {@code PJ} structure allocated in the C/C++ heap. This value has no
-     * meaning in Java code. <strong>Do not modify</strong>, since this value is used by Proj4.
-     * Do not rename neither, unless you update accordingly the C code in JNI wrappers.
+     * The pointer to {@code PJ} structure allocated in the C/C++ heap. This value has no meaning in Java code.
+     * <strong>Do not modify</strong>, since this value is used by Proj. Do not rename neither, unless you update
+     * accordingly the C code in JNI wrappers.
      */
     private final long ptr;
 
     /**
-     * Creates a new {@code PJ} structure from the given Proj4 definition string.
+     * Creates a new {@code PJ} structure from the given Proj definition string.
      *
-     * @param  definition The Proj.4 definition string.
-     * @throws IllegalArgumentException If the PJ structure can not be created from the given string.
+     * @param  definition  the Proj definition string.
+     * @throws IllegalArgumentException if the PJ structure can not be created from the given string.
      */
     public PJ(final String definition) throws IllegalArgumentException {
+        Objects.requireNonNull(definition);
         ptr = allocatePJ(definition);
         if (ptr == 0) {
             throw new IllegalArgumentException(definition);
@@ -87,15 +89,12 @@ public class PJ {
      * {@linkplain org.opengis.referencing.crs.ProjectedCRS#getBaseCRS() base geographic CRS}
      * from a {@linkplain org.opengis.referencing.crs.ProjectedCRS projected CRS}.
      *
-     * @param  crs The CRS (usually projected) from which to derive a new CRS.
-     * @param  type The type of the new CRS. Currently, only {@link Type#GEOGRAPHIC} is supported.
-     * @throws IllegalArgumentException If the PJ structure can not be created.
+     * @param  crs   the CRS (usually projected) from which to derive a new CRS.
+     * @param  type  the type of the new CRS. Currently, only {@link Type#GEOGRAPHIC} is supported.
+     * @throws IllegalArgumentException if the PJ structure can not be created.
      */
     public PJ(final PJ crs, final Type type) throws IllegalArgumentException {
-        if (crs == null) {
-            // TODO: Use Objects with JDK 7.
-            throw new NullPointerException("The CRS must be non-null.");
-        }
+        Objects.requireNonNull(crs, "The CRS must be non-null.");
         if (type != Type.GEOGRAPHIC) {
             throw new IllegalArgumentException("Can not derive the " + type + " type.");
         }
@@ -111,8 +110,8 @@ public class PJ {
      * to the {@link #ptr} field. The allocated structure is released by the {@link #finalize()}
      * method.
      *
-     * @param  definition The Proj4 definition string.
-     * @return A pointer to the PJ native data structure, or 0 if the operation failed.
+     * @param  definition  the Proj definition string.
+     * @return a pointer to the PJ native data structure, or 0 if the operation failed.
      */
     private static native long allocatePJ(String definition);
 
@@ -122,39 +121,41 @@ public class PJ {
      * the return value <strong>must</strong> be assigned to the {@link #ptr} field.
      * The allocated structure is released by the {@link #finalize()} method.
      *
-     * @param  projected The CRS from which to derive the base geographic CRS.
-     * @return A pointer to the PJ native data structure, or 0 if the operation failed.
+     * @param  projected  the CRS from which to derive the base geographic CRS.
+     * @return a pointer to the PJ native data structure, or 0 if the operation failed.
      */
     private static native long allocateGeoPJ(PJ projected);
 
     /**
-     * Returns the version number of the Proj4 library.
+     * Returns the version number of the Proj library.
      *
-     * @return The Proj.4 release string.
+     * @return the Proj release string.
      */
     public static native String getVersion();
 
     /**
-     * Returns the Proj4 definition string. This is the string given to the constructor,
+     * Returns the Proj definition string. This is the string given to the constructor,
      * expanded with as much information as possible.
      *
-     * @return The Proj4 definition string.
+     * @return the Proj definition string.
      */
     public native String getDefinition();
 
     /**
      * Returns the Coordinate Reference System type.
      *
-     * @return The CRS type.
+     * @return the CRS type.
      */
     public native Type getType();
 
     /**
      * The coordinate reference system (CRS) type returned by {@link PJ#getType()}.
-     * In the Proj.4 library, a CRS can only be geographic, geocentric or projected,
+     * In the Proj library, a CRS can only be geographic, geocentric or projected,
      * without distinction between 2D and 3D CRS.
      *
      * @author  Martin Desruisseaux (Geomatys)
+     * @version 5.1
+     * @since   4.8
      */
     public static enum Type {
         /*
@@ -184,7 +185,7 @@ public class PJ {
     /**
      * Returns the value stored in the {@code a_orig} PJ field.
      *
-     * @return The axis length stored in {@code a_orig}.
+     * @return the axis length stored in {@code a_orig}.
      *
      * @see org.opengis.referencing.datum.Ellipsoid#getSemiMajorAxis()
      */
@@ -193,18 +194,18 @@ public class PJ {
     /**
      * Returns the value computed from PJ fields by {@code √((a_orig)² × (1 - es_orig))}.
      *
-     * @return The axis length computed by {@code √((a_orig)² × (1 - es_orig))}.
+     * @return the axis length computed by {@code √((a_orig)² × (1 - es_orig))}.
      *
      * @see org.opengis.referencing.datum.Ellipsoid#getSemiMinorAxis()
      */
     public native double getSemiMinorAxis();
 
     /**
-     * Returns the square of the ellipsoid eccentricity (&epsilon;&sup2;). The eccentricity
-     * is related to axis length by &epsilon;=√(1-(<var>b</var>/<var>a</var>)&sup2;). The
+     * Returns the square of the ellipsoid eccentricity (ε²). The eccentricity
+     * is related to axis length by ε=√(1-(<var>b</var>/<var>a</var>)²). The
      * eccentricity of a sphere is zero.
      *
-     * @return The eccentricity.
+     * @return the eccentricity.
      *
      * @see org.opengis.referencing.datum.Ellipsoid#isSphere()
      * @see org.opengis.referencing.datum.Ellipsoid#getInverseFlattening()
@@ -213,9 +214,9 @@ public class PJ {
 
     /**
      * Returns an array of character indicating the direction of each axis. Directions are
-     * characters like {@code 'e'} for East, {@code 'n'} for North and {@code 'u'} for Up.
+     * characters like {@code 'e'} for East, {@code 'n'} for North and {@code 'u'} for Up.
      *
-     * @return The axis directions.
+     * @return the axis directions.
      *
      * @see org.opengis.referencing.cs.CoordinateSystemAxis#getDirection()
      */
@@ -224,7 +225,7 @@ public class PJ {
     /**
      * Longitude of the prime meridian measured from the Greenwich meridian, positive eastward.
      *
-     * @return The prime meridian longitude, in degrees.
+     * @return the prime meridian longitude, in degrees.
      *
      * @see org.opengis.referencing.datum.PrimeMeridian#getGreenwichLongitude()
      */
@@ -235,32 +236,30 @@ public class PJ {
      *
      * @param  vertical {@code false} for the conversion factor of horizontal axes,
      *         or {@code true} for the conversion factor of the vertical axis.
-     * @return The conversion factor to metres for the given axis.
+     * @return the conversion factor to metres for the given axis.
      */
     public native double getLinearUnitToMetre(boolean vertical);
 
     /**
-     * Transforms in-place the coordinates in the given array. The coordinates array shall contain
-     * (<var>x</var>,<var>y</var>,<var>z</var>,&hellip;) tuples, where the <var>z</var> and
-     * following dimensions are optional. Note that any dimension after the <var>z</var> value
-     * are ignored.
-     * <p>
-     * Input and output units:
-     * <p>
+     * Transforms in-place the coordinates in the given array.
+     * The coordinates array shall contain (<var>x</var>,<var>y</var>,<var>z</var>,…) tuples,
+     * where the <var>z</var> and any additional dimensions are optional.
+     * Note that any dimension after the <var>z</var> value are ignored.
+     *
+     * <p>Input and output units:</p>
      * <ul>
      *   <li>Angular units (as in longitude and latitudes) are decimal degrees.</li>
      *   <li>Linear units are usually metres, but this is actually projection-dependent.</li>
      * </ul>
      *
-     * @param  target The target CRS.
-     * @param  dimension The dimension of each coordinate value. Must be in the [2-{@value #DIMENSION_MAX}] range.
-     * @param  coordinates The coordinates to transform, as a sequence of
-     *         (<var>x</var>,<var>y</var>,&lt;<var>z</var>&gt;,&hellip;) tuples.
-     * @param  offset Offset of the first coordinate in the given array.
-     * @param  numPts Number of points to transform.
-     * @throws NullPointerException If the {@code target} or {@code coordinates} argument is null.
+     * @param  target       the target CRS.
+     * @param  dimension    the dimension of each coordinate value. Must be in the [2-{@value #DIMENSION_MAX}] range.
+     * @param  coordinates  the coordinates to transform, as a sequence of (<var>x</var>,<var>y</var>,&lt;<var>z</var>&gt;,…) tuples.
+     * @param  offset       offset of the first coordinate in the given array.
+     * @param  numPts       number of points to transform.
+     * @throws NullPointerException if the {@code target} or {@code coordinates} argument is null.
      * @throws IndexOutOfBoundsException if the {@code offset} or {@code numPts} arguments are invalid.
-     * @throws PJException If the operation failed for an other reason (provided by Proj4).
+     * @throws PJException if the operation failed for another reason (provided by Proj).
      *
      * @see org.opengis.referencing.operation.MathTransform#transform(double[], int, double[], int, int)
      */
@@ -270,24 +269,23 @@ public class PJ {
     /**
      * Returns a description of the last error that occurred, or {@code null} if none.
      *
-     * @return The last error that occurred, or {@code null}.
+     * @return the last error that occurred, or {@code null}.
      */
     public native String getLastError();
 
     /**
      * Returns the string representation of the PJ structure.
      *
-     * @return The string representation.
+     * @return the string representation.
      */
     @Override
     public native String toString();
 
     /**
-     * Deallocates the native PJ data structure. This method can be invoked only by the garbage
-     * collector, and must be invoked exactly once (no more, no less).
-     * <strong>NEVER INVOKE THIS METHOD EXPLICITLY, NEVER OVERRIDE</strong>.
+     * Deallocates the native PJ data structure.
+     * This method should be invoked exactly once, only by the garbage collector,
      */
     @Override
-    @SuppressWarnings("deprecation")
+    @SuppressWarnings({"deprecation", "FinalizeDeclaration"})
     protected final native void finalize();
 }
diff --git a/jniwrap/org/proj4/PJException.java b/jniwrap/org/proj4/PJException.java
index 18a58851..4b465e6a 100644
--- a/jniwrap/org/proj4/PJException.java
+++ b/jniwrap/org/proj4/PJException.java
@@ -1,10 +1,10 @@
 /******************************************************************************
  * Project:  PROJ.4
- * Purpose:  Java/JNI wrappers for PROJ.4 API.
+ * Purpose:  Java/JNI wrappers for PROJ API.
  * Author:   Martin Desruisseaux
  *
  ******************************************************************************
- * Copyright (c) 2011, Open Geospatial Consortium, Inc.
+ * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -23,10 +23,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
- *****************************************************************************
- * This file is a copy of a file developed in the GeoAPI "Proj.4 binding"
- * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is
- * modified, please consider synchronizing the changes with GeoAPI.
+ ******************************************************************************
  */
 package org.proj4;
 
@@ -35,6 +32,8 @@ package org.proj4;
  * Exception thrown when a call to {@link PJ#transform(PJ, int, double[], int, int)} failed.
  *
  * @author  Martin Desruisseaux (Geomatys)
+ * @version 5.1
+ * @since   4.8
  */
 public class PJException extends Exception {
     /**
@@ -52,7 +51,7 @@ public class PJException extends Exception {
     /**
      * Constructs a new exception with the given message.
      *
-     * @param message A message that describe the cause for the failure.
+     * @param message  a message that describe the cause for the failure.
      */
     public PJException(final String message) {
         super(message);
diff --git a/jniwrap/org/proj4/package-info.java b/jniwrap/org/proj4/package-info.java
index 8a6b75a3..d69fb807 100644
--- a/jniwrap/org/proj4/package-info.java
+++ b/jniwrap/org/proj4/package-info.java
@@ -1,10 +1,10 @@
 /******************************************************************************
  * Project:  PROJ.4
- * Purpose:  Java/JNI wrappers for PROJ.4 API.
+ * Purpose:  Java/JNI wrappers for PROJ API.
  * Author:   Martin Desruisseaux
  *
  ******************************************************************************
- * Copyright (c) 2011, Open Geospatial Consortium, Inc.
+ * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -23,18 +23,17 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
- *****************************************************************************
- * This file is a copy of a file developed in the GeoAPI "Proj.4 binding"
- * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is
- * modified, please consider synchronizing the changes with GeoAPI.
+ ******************************************************************************
  */
 
 /**
- * Wrappers for the <a href="http://proj.osgeo.org/">Proj4</a> library. The {@link org.proj4.PJ}
- * class contains only native methods delegating their work to the Proj.4 library.
+ * Wrappers for the <a href="http://proj4.org/">Proj</a> library.
+ * The {@link org.proj4.PJ} class contains only native methods delegating their work to the Proj library.
  * For higher-level methods making use of those native methods, see for example the
- * <a href="http://www.geoapi.org/geoapi-proj4/index.html">GeoAPI bindings for Proj.4</a>.
+ * <a href="http://www.geoapi.org/geoapi-proj4/index.html">GeoAPI bindings for Proj</a>.
  *
  * @author  Martin Desruisseaux (Geomatys)
+ * @version 5.1
+ * @since   4.8
  */
 package org.proj4;