Author: desruisseaux
Date: Sun Feb 1 22:17:37 2015
New Revision: 1656370
URL: http://svn.apache.org/r1656370
Log:
Documentation updates. In particular explain better what a MathTransform is,
and its relationship with Formula.
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/AbstractFactory.java
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java?rev=1656370&r1=1656369&r2=1656370&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java
[UTF-8] Sun Feb 1 22:17:37 2015
@@ -33,11 +33,20 @@ import java.util.Objects;
/**
* Specification of the coordinate operation method formula.
+ * A formula may be {@linkplain #getFormula() given textually},
+ * or may be a {@linkplain #getCitation() reference to a publication}.
+ *
+ * <p>{@code Formula} is for human reading.
+ * The object that actually does the work of applying formula to coordinate
values is
+ * {@link org.opengis.referencing.operation.MathTransform}.</p>
*
* @author Martin Desruisseaux (Geomatys)
* @version 0.5
* @since 0.5
* @module
+ *
+ * @see DefaultOperationMethod
+ * @see org.apache.sis.referencing.operation.transform.AbstractMathTransform
*/
public class DefaultFormula extends FormattableObject implements Formula,
Serializable {
/**
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java?rev=1656370&r1=1656369&r2=1656370&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] Sun Feb 1 22:17:37 2015
@@ -47,18 +47,23 @@ import static org.apache.sis.util.Argume
/**
* Provides a default implementation for most methods required by the {@link
MathTransform} interface.
- * {@code AbstractMathTransform} provides a convenient base class from which
transform implementations
+ * A {@code MathTransform} is an object that actually does the work of
applying a
+ * {@linkplain org.apache.sis.referencing.operation.DefaultFormula formula} to
coordinate values.
+ * The math transform does not know or care how the coordinates relate to
positions in the real world.
+ * For example if an affine transform scales <var>z</var> values by a factor
of 1000,
+ * then it could be converting metres to millimetres, or it could be
converting kilometres to metres.
+ *
+ * <p>{@code AbstractMathTransform} provides a convenient base class from
which {@code MathTransform} implementations
* can be easily derived. It also defines a few additional SIS-specific
methods for convenience of performance.
+ * The simplest way to implement this abstract class is to provide an
implementation for the following methods only:</p>
*
- * <p>The simplest way to implement this abstract class is to provide an
implementation for the following methods
- * only:</p>
* <ul>
* <li>{@link #getSourceDimensions()}</li>
* <li>{@link #getTargetDimensions()}</li>
* <li>{@link #transform(double[], int, double[], int, boolean)}</li>
* </ul>
*
- * However more performance may be gained by overriding the other {@code
transform} methods as well.
+ * However more performance may be gained by overriding the other {@code
transform(…)} methods as well.
*
* {@section Immutability and thread safety}
* All Apache SIS implementations of {@code MathTransform} are immutable and
thread-safe.
Modified:
sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/AbstractFactory.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/AbstractFactory.java?rev=1656370&r1=1656369&r2=1656370&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/AbstractFactory.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/AbstractFactory.java
[UTF-8] Sun Feb 1 22:17:37 2015
@@ -39,7 +39,7 @@ public abstract class AbstractFactory im
/**
* Returns the implementor of this factory, or {@code null} if unknown.
* The default implementation tries to fetch this information from the
- * manifest associated to the package of this class.
+ * manifest associated to the package of {@code this.getClass()}.
*
* @return The vendor for this factory implementation, or {@code null} if
unknown.
*
