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 <[email protected]>
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
