sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] branch geoapi-4.0 updated: Javadoc clarification, second round.
Date Wed, 05 Feb 2020 19:25:37 GMT
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


The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
     new fc88ca5  Javadoc clarification, second round.
fc88ca5 is described below

commit fc88ca54189ae45243e7528fd5e7d774f926d2a1
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Feb 5 20:25:03 2020 +0100

    Javadoc clarification, second round.
---
 .../java/org/apache/sis/internal/map/MapItem.java  | 12 +++++-----
 .../java/org/apache/sis/internal/map/MapLayer.java |  2 +-
 .../org/apache/sis/internal/map/MapLayers.java     | 22 ++++++++---------
 .../org/apache/sis/internal/map/Presentation.java  | 28 ++++++++++++----------
 4 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
index 09cdeae..af19c94 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapItem.java
@@ -29,24 +29,24 @@ import org.apache.sis.util.ArraysExt;
 
 
 /**
- * Parent class of all elements having a graphical representation on the map.
- * This base class does not make any assumption about how this {@code MapItem} will be rendered;
- * the actual feature or coverage data, together with styling information, are provided by
subclasses.
+ * Base class of map layer or group of map layers. This base class does not represent graphical
elements.
+ * Instead it contains information (data and style) for creating a tree of {@link Presentation}
objects.
  * A {@code MapItem} contains the following properties:
  *
  * <ul>
  *   <li>An {@linkplain #getIdentifier() identifier}, which can be any {@link String}
at developer choice.</li>
  *   <li>A human-readable {@linkplain #getTitle() title} for pick lists, for example
in GUI.</li>
- *   <li>A {@linkplain #getAbstract() narrative description} providing additional information.</li>
+ *   <li>A {@linkplain #getAbstract() narrative description} providing more details.</li>
  * </ul>
  *
  * Additional information can be added in a map of {@linkplain #getUserProperties() user
properties}.
+ * The actual feature or coverage data, together with styling information, are provided by
subclasses.
  *
  * <h2>Synchronization</h2>
  * {@code MapItem} instances are not thread-safe. Synchronization, if desired, is caller
responsibility.
  *
- * @todo Consider renaming as {@code Graphic} for emphasis that this is a graphical representation
of something.
- *       This would be consistent with legacy GO-1 specification (even if retired, it still
have worthy material).
+ * @todo Rename as {@code MapNode}? "Item" suggests an element in a list, while {@link MapLayers}
actually
+ *       creates a tree.
  *
  * @author  Johann Sorel (Geomatys)
  * @version 1.1
diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
index 4ec3050..cf0d363 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayer.java
@@ -27,7 +27,7 @@ import org.apache.sis.storage.Aggregate;
 
 
 /**
- * Data (resource) associated to visual representation (symbology).
+ * Data (resource) associated to rules for visual representation (symbology).
  * Layers are the key elements of a map: they link data (given by {@link Resource}s) or a
subset of
  * those data (filtered by {@link Query}) to their visual representation (defined by {@link
Style}s).
  * The visual appearance of a layer should be similar with any rendering engine.
diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
index c39f3c7..d7e069d 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/MapLayers.java
@@ -25,19 +25,17 @@ import org.apache.sis.storage.DataSet;
 
 
 /**
- * A group of graphic elements to display together.
+ * A group of layers to display together.
  * {@code MapLayers} can be used for grouping related layers under a same node.
- * This allows global actions, like {@linkplain #setVisible(boolean) hiding}
- * background layers in one call.
+ * This allows global actions, like {@linkplain #setVisible(boolean) hiding} background layers
in one call.
+ * A {@code MapLayers} can also contain nested {@code MapLayers}, thus forming a tree.
+ * Since {@link MapLayer} and {@code MapLayers} are the only {@link MapItem} subclasses,
+ * all leaves in this tree can only be {@link MapLayer} instances (assuming no {@code MapLayers}
is empty).
  *
  * <p>A {@code MapLayers} is often (but not necessarily) the root node of the tree
of all graphic elements to
- * draw on the map. Those elements are typically {@link MapLayer} instances, but more generic
{@link MapItem}
- * instances are also accepted. Those elements are listed by {@link #getComponents()} in
<var>z</var> order.
- * In addition, {@code MapLayers} defines the {@linkplain #getAreaOfInterest() area of interest}
- * which should be zoomed by default when the map is rendered.</p>
- *
- * @todo Despite its name, this class is not a container of {@link MapLayer}s since it accepts
more generic objects.
- *       Consider renaming as {@code Group} or {@code GraphicAggregate}.
+ * draw on the map. The {@link MapItem} children are listed by {@link #getComponents()} in
<var>z</var> order.
+ * In addition, {@code MapLayers} defines the {@linkplain #getAreaOfInterest() area of interest}
which should
+ * be zoomed by default when the map is rendered.</p>
  *
  * @author  Johann Sorel (Geomatys)
  * @version 1.1
@@ -52,7 +50,7 @@ public class MapLayers extends MapItem {
      * @see #getAreaOfInterest()
      * @see #setAreaOfInterest(Envelope)
      */
-    public static final String AREAOFINTEREST_PROPERTY = "areaOfInterest";
+    public static final String AREA_OF_INTEREST_PROPERTY = "areaOfInterest";
 
     /**
      * The components in this group, or an empty list if none.
@@ -118,7 +116,7 @@ public class MapLayers extends MapItem {
         final Envelope oldValue = areaOfInterest;
         if (!Objects.equals(oldValue, newValue)) {
             areaOfInterest = newValue;
-            firePropertyChange(AREAOFINTEREST_PROPERTY, oldValue, newValue);
+            firePropertyChange(AREA_OF_INTEREST_PROPERTY, oldValue, newValue);
         }
     }
 }
diff --git a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
index 92ee82f..c1b0e29 100644
--- a/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
+++ b/core/sis-portrayal/src/main/java/org/apache/sis/internal/map/Presentation.java
@@ -17,27 +17,29 @@
 package org.apache.sis.internal.map;
 
 import org.opengis.feature.Feature;
+import org.apache.sis.storage.Resource;
+import org.apache.sis.coverage.grid.GridCoverage;
 
 
 /**
- * When rendering resources, the first step is to generate the visual aspect
- * of each feature or coverage, we call each one a Presentation.
- * <p>
- * A presentation object must be a simplistic description without any evaluation,
- * processing or loading work remaining.
- * </p>
- * <p>
- * It is important to note that multiple presentations may be generated for the
- * same feature.
- * </p>
+ * Parent class of all elements having a graphical representation on the map.
+ * {@code Presentation} instances are organized in a tree parallel to the {@link MapLayer}
tree.
+ * The {@link MapLayer} tree links data and styles in a device-independent way, while
+ * the {@code Presentation} tree can be seen as map layers information "compiled"
+ * in a form more directly exploitable by the display device.
+ * In particular a {@code Presentation} objects must encapsulate data without
+ * costly evaluation, processing or loading work remaining to be done.
+ * (for example {@link Feature} or {@link GridCoverage} instances instead than {@link Resource}s).
+ *
+ * <p>Note that multiple presentations may be generated for the same feature.
+ * Consequently many {@code Presentation} instances may encapsulate the same {@link Feature}
instances.</p>
  *
  * <p>
  * NOTE: this class is a first draft subject to modifications.
  * </p>
  *
- * @todo Maybe should be not be part of public API. This functionality could be done with
a
- *       {@link MapItem} subclasses containing only a {@link Feature} or {@code GridCoverage}
- *       instance, as opposed to {@link MapLayer} containing {@code Resource}.
+ * @todo Consider renaming as {@code Graphic} for emphasis that this is a graphical representation
of something.
+ *       This would be consistent with legacy GO-1 specification (even if retired, it still
have worthy material).
  *
  * @author  Johann Sorel (Geomatys)
  * @version 1.1


Mime
View raw message