Adjustments in documentation and in deprecations.

geoapi-conformance/src/main/java/org/opengis/test/ValidatorContainer.java

@@ -695,8 +695,7 @@ public final void validate(final DerivedCRS object) {
      *
      * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public final void validate(final ImageCRS object) {
         crs.validate(object);
     }
@@ -851,8 +850,7 @@ public final void validate(final TimeCS object) {
      *
      * @see CSValidator#validate(UserDefinedCS)
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public final void validate(final UserDefinedCS object) {
         cs.validate(object);
     }
@@ -940,7 +938,11 @@ public final void validate(final TemporalDatum object) {
      * @param  object  the object to test, or {@code null}.
      *
      * @see DatumValidator#validate(ImageDatum)
+     *
+     * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
+    @Deprecated(since="3.1")
+    @SuppressWarnings("removal")
     public final void validate(final ImageDatum object) {
         datum.validate(object);
     }

geoapi-conformance/src/main/java/org/opengis/test/Validators.java

@@ -512,8 +512,7 @@ public static void validate(final DerivedCRS object) {
      *
      * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public static void validate(final ImageCRS object) {
         DEFAULT.validate(object);
     }
@@ -668,8 +667,7 @@ public static void validate(final TimeCS object) {
      *
      * @see CSValidator#validate(UserDefinedCS)
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public static void validate(final UserDefinedCS object) {
         DEFAULT.validate(object);
     }
@@ -757,7 +755,11 @@ public static void validate(final TemporalDatum object) {
      * @param  object  the object to test, or {@code null}.
      *
      * @see DatumValidator#validate(ImageDatum)
+     *
+     * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
+    @Deprecated(since="3.1")
+    @SuppressWarnings("removal")
     public static void validate(final ImageDatum object) {
         DEFAULT.validate(object);
     }

geoapi-conformance/src/main/java/org/opengis/test/referencing/CRSValidator.java

@@ -306,8 +306,7 @@ private void validateGeneralDerivedCRS(final DerivedCRS object) {
      *
      * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public void validate(final ImageCRS object) {
         if (object == null) {
             return;

geoapi-conformance/src/main/java/org/opengis/test/referencing/CSValidator.java

@@ -299,8 +299,7 @@ public void validate(final TimeCS object) {
      *
      * @param  object  the object to validate, or {@code null}.
      */
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public void validate(final UserDefinedCS object) {
         if (object == null) {
             return;

geoapi-conformance/src/main/java/org/opengis/test/referencing/PseudoEpsgFactory.java

@@ -304,8 +304,11 @@ public EngineeringDatum createEngineeringDatum(String code) throws FactoryExcept
      * The default implementation throws {@link NoSuchAuthorityCodeException} unconditionally.
      *
      * @throws FactoryException if this method cannot provide the requested information.
+     *
+     * @deprecated {@code ImageDatum} is replaced by {@link EngineeringDatum} as of ISO 19111:2019.
      */
     @Override
+    @Deprecated(since="3.1")
     public ImageDatum createImageDatum(String code) throws FactoryException {
         final int id = parseCode(code);
         switch (id) {
@@ -994,8 +997,7 @@ public GeocentricCRS createGeocentricCRS(String code) throws FactoryException {
      * @deprecated {@code ImageCRS} is replaced by {@link EngineeringCRS} as of ISO 19111:2019.
      */
     @Override
-    @SuppressWarnings("removal")
-    @Deprecated(since="3.1", forRemoval=true)
+    @Deprecated(since="3.1")
     public ImageCRS createImageCRS(String code) throws FactoryException {
         final int id = parseCode(code);
         switch (id) {

geoapi-conformance/src/main/java/org/opengis/test/wkt/CRSParserTest.java

@@ -19,6 +19,7 @@
 
 import java.util.Date;
 import java.util.List;
+import java.util.Optional;
 import javax.measure.Unit;
 import javax.measure.quantity.Angle;
 import javax.measure.quantity.Length;
@@ -175,7 +176,7 @@ private static void verifyAxisAbbreviations(final CoordinateSystem cs, final Str
     }
 
     /**
-     * Asserts the given character sequence is either null or equals to the given value.
+     * Asserts the given character sequence is either null or equal to the given value.
      * This is used for optional elements like remarks.
      *
      * @param property  the property being tested, for producing a message in case of assertion failure.
@@ -188,6 +189,20 @@ private static void assertNullOrEquals(final String property, final String expec
         }
     }
 
+    /**
+     * Asserts the given character sequence is either empty or equal to the given value.
+     * This is used for optional elements like remarks.
+     *
+     * @param property  the property being tested, for producing a message in case of assertion failure.
+     * @param expected  the expected value.
+     * @param actual    the actual value.
+     */
+    private static void assertEmptyOrEquals(String property, String expected, Optional<? extends CharSequence> actual) {
+        if (actual.isPresent()) {
+            assertEquals(expected, actual.get().toString(), property);
+        }
+    }
+
     /**
      * Pre-process the WKT string before parsing.
      * The default implementation performs the following changes for strict ISO 19162 compliance:
@@ -1002,7 +1017,7 @@ public void testEngineeringRotated() throws FactoryException {
 
         verifyIdentification   (crs, "A construction site CRS", null);
         verifyDatum            (crs.getDatum(), "P1");
-        assertNullOrEquals     ("datum.anchor", "Peg in south corner", crs.getDatum().getAnchorPoint());
+        assertEmptyOrEquals    ("datum.anchor", "Peg in south corner", crs.getDatum().getAnchorDefinition());
         verifyCoordinateSystem (crs.getCoordinateSystem(), CartesianCS.class, new AxisDirection[] {SOUTH_WEST, SOUTH_EAST}, metre);
     }
 
@@ -1045,7 +1060,7 @@ public void testEngineeringForShip() throws FactoryException {
 
         verifyIdentification   (crs, "A ship-centred CRS", null);
         verifyDatum            (crs.getDatum(), "Ship reference point");
-        assertNullOrEquals     ("datum.anchor", "Centre of buoyancy", crs.getDatum().getAnchorPoint());
+        assertEmptyOrEquals    ("datum.anchor", "Centre of buoyancy", crs.getDatum().getAnchorDefinition());
         verifyAxisAbbreviations(cs = crs.getCoordinateSystem(), "x", "y", "z");
         verifyCoordinateSystem (cs, CartesianCS.class, new AxisDirection[] {valueOf("forward"), valueOf("starboard"), DOWN}, metre);
     }

geoapi/src/main/java/org/opengis/annotation/Obligation.java

@@ -60,7 +60,7 @@ public enum Obligation implements ControlledVocabulary {
     /**
      * The element should always be {@code null}. This obligation code is used only when
      * a sub-interface overrides an association and force it to a {@code null} value.
-     * An example is {@link org.opengis.referencing.datum.TemporalDatum#getAnchorPoint()}.
+     * An example is {@link org.opengis.referencing.datum.TemporalDatum#getAnchorDefinition()}.
      *
      * @departure constraint
      *   ISO specifications sometimes override a parent method with a comment saying that the method

geoapi/src/main/java/org/opengis/referencing/datum/Datum.java

@@ -71,10 +71,10 @@ public interface Datum extends IdentifiedObject {
     /**
      * Key for the <code>{@value}</code> property to be given to the
      * {@code DatumFactory.createFoo(Map, ...)} methods.
-     * This is used for setting the value to be returned by {@link #getAnchorPoint()}.
+     * This is used for setting the value to be returned by {@link #getAnchorDefinition()}.
      *
      * @see DatumFactory
-     * @see #getAnchorPoint()
+     * @see #getAnchorDefinition()
      *
      * @deprecated Renamed {@link #ANCHOR_DEFINITION_KEY} for conformance with ISO 19111:2019 revision.
      */
@@ -153,7 +153,7 @@ public interface Datum extends IdentifiedObject {
     String CONVENTIONAL_RS_KEY = "conventionalRS";
 
     /**
-     * A description of the relationship used to anchor the coordinate system to the Earth or alternate object.
+     * Returns a description of the relationship used to anchor the coordinate system to the Earth or alternate object.
      * The definition may include coordinates of an identified point or points.
      * Also known as the "origin", especially for {@link EngineeringDatum}s.
      *
@@ -194,7 +194,7 @@ default InternationalString getAnchorPoint() {
     }
 
     /**
-     * Epoch at which a static reference frame matches a dynamic reference frame from which it has been derived.
+     * Returns the epoch at which a static datum matches a dynamic datum from which it has been derived.
      * This time may be precise or merely a year (e.g. 1983 for NAD83). In the latter case, the epoch usually
      * refers to the year in which a major recalculation of the geodetic control network, underlying the datum,
      * was executed or initiated.
@@ -203,7 +203,7 @@ default InternationalString getAnchorPoint() {
      * Nor with the epoch at which a reference frame is defined to be aligned with another reference frame.
      * this information should be included in the datum {@linkplain #getAnchorDefinition() anchor definition}.</p>
      *
-     * @return epoch at which a static reference frame matches a dynamic reference frame from which it has been derived.
+     * @return epoch at which a static datum matches a dynamic datum from which it has been derived.
      *
      * @see java.time.Year
      * @see java.time.YearMonth
@@ -262,7 +262,7 @@ default InternationalString getScope() {
     }
 
     /**
-     * Date on which the datum definition was published.
+     * Returns the date on which the datum definition was published.
      *
      * @return date on which the datum definition was published.
      *
@@ -277,7 +277,7 @@ default Optional<CitationDate> getPublicationDate() {
     }
 
     /**
-     * Name, identifier, alias and remarks for the reference system realized by this reference frame.
+     * Returns the name, identifier, alias and remarks for the reference system realized by this reference frame.
      * Examples: "ITRS" for ITRF88 through ITRF2008 and ITRF2014, or "EVRS" for EVRF2000 and EVRF2007.
      * All datums that are members of a {@linkplain DatumEnsemble datum ensemble} shall have the same
      * conventional reference system.

geoapi/src/main/java/org/opengis/referencing/datum/DatumAuthorityFactory.java

@@ -214,7 +214,10 @@ default EngineeringDatum createEngineeringDatum(final String code) throws Factor
      * @throws FactoryException if the object creation failed for some other reason.
      *
      * @see org.opengis.referencing.crs.CRSAuthorityFactory#createImageCRS(String)
+     *
+     * @deprecated {@code ImageDatum} is replaced by {@link EngineeringDatum} as of ISO 19111:2019.
      */
+    @Deprecated(since="3.1")
     default ImageDatum createImageDatum(final String code) throws FactoryException {
         final Datum datum = createDatum(code);
         try {

geoapi/src/main/java/org/opengis/referencing/datum/DatumFactory.java

@@ -198,7 +198,10 @@ default EngineeringDatum createEngineeringDatum(Map<String,?> properties) throws
      *         with the image data attributes.
      * @return the datum for the given properties.
      * @throws FactoryException if the object creation failed.
+     *
+     * @deprecated {@code ImageDatum} is replaced by {@link EngineeringDatum} as of ISO 19111:2019.
      */
+    @Deprecated(since="3.1")
     default ImageDatum createImageDatum(Map<String,?> properties,
                                         PixelInCell   pixelInCell) throws FactoryException
     {

geoapi/src/main/java/org/opengis/referencing/datum/DynamicReferenceFrame.java

@@ -52,7 +52,7 @@
 @Classifier(Stereotype.ABSTRACT)
 public interface DynamicReferenceFrame extends Datum {
     /**
-     * Epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.
+     * Returns the epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.
      *
      * <h4>Temporal object type</h4>
      * The type of the returned object depends on the epoch accuracy and the calendar in use.