You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2012/10/20 13:00:58 UTC
svn commit: r1400418 - in /sis/branches/JDK7:
sis-utility/src/main/java/org/apache/sis/math/
sis-utility/src/main/java/org/apache/sis/util/
sis-utility/src/main/java/org/apache/sis/util/logging/
sis-utility/src/main/java/org/apache/sis/xml/ src/main/ja...
Author: desruisseaux
Date: Sat Oct 20 11:00:57 2012
New Revision: 1400418
URL: http://svn.apache.org/viewvc?rev=1400418&view=rev
Log:
Javadoc formatting (hopefully last for a little while), and added a page listing the custom styles.
Added:
sis/branches/JDK7/src/site/apt/code-format.apt
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Characters.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerAdapter.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XLink.java
sis/branches/JDK7/src/main/javadoc/stylesheet.css
sis/branches/JDK7/src/site/apt/index.apt
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java Sat Oct 20 11:00:57 2012
@@ -298,7 +298,7 @@ public final class MathFunctions extends
*
* As seen from the above cases, this method distinguishes positive zero from negative zero.
* The handling of zero values is the difference between invoking {@code isPositive(double)}
- * and testing if (<var>value</var> >= 0).
+ * and testing if (<var>value</var> {@literal >= 0}).
*
* @param value The value to test.
* @return {@code true} if the given value is positive, excluding negative zero.
@@ -319,7 +319,7 @@ public final class MathFunctions extends
*
* As seen from the above cases, this method distinguishes positive zero from negative zero.
* The handling of zero values is the difference between invoking {@code isNegative(double)}
- * and testing if (<var>value</var> < 0).
+ * and testing if (<var>value</var> {@literal < 0}).
*
* @param value The value to test.
* @return {@code true} if the given value is negative, including negative zero.
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java Sat Oct 20 11:00:57 2012
@@ -136,12 +136,12 @@ public final class Arrays extends Static
* <ul>
* <li>If the given {@code length} is longer than the length of the given {@code array},
* then the returned array will contain all the elements of {@code array} at index
- * <var>i</var> < {@code array.length}. Elements at index
- * <var>i</var> >= {@code array.length} are initialized to {@code null}.</li>
+ * <var>i</var>Â {@literal <}Â {@code array.length}. Elements at index
+ * <var>i</var>Â {@literal >=}Â {@code array.length} are initialized to {@code null}.</li>
*
* <li>If the given {@code length} is shorter than the length of the given {@code array},
* then the returned array will contain only the elements of {@code array} at index
- * <var>i</var> < {@code length}. Remaining elements are not copied.</li>
+ * <var>i</var>Â {@literal <}Â {@code length}. Remaining elements are not copied.</li>
*
* <li>If the given {@code length} is equal to the length of the given {@code array},
* then {@code array} is returned unchanged. <strong>No copy</strong> is performed.
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Characters.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Characters.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Characters.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Characters.java Sat Oct 20 11:00:57 2012
@@ -27,7 +27,7 @@ package org.apache.sis.util;
*/
public final class Characters extends Static {
/**
- * The <cite>no-break space</cite> (Unicode {@code \\u00A0}, HTML {@code }).
+ * The <cite>no-break space</cite> (Unicode <code>\\u00A0</code>, HTML {@code }).
* Apache SIS uses Unicode symbols directly in the source code for easier reading,
* except for no-break spaces since they can not be visually distinguished from the
* ordinary space (Unicode {@code \u0020}).
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java Sat Oct 20 11:00:57 2012
@@ -26,12 +26,12 @@ package org.apache.sis.util;
* <p>This enumeration is <em>ordered</em> from stricter to more lenient degrees:</p>
*
* <ol>
- * <li>{@link #STRICT}: All attributes of the compared objects shall be strictly equal.</li>
- * <li>{@link #BY_CONTRACT}: Only the attributes published in the interface contract need to be compared.</li>
- * <li>{@link #IGNORE_METADATA}: Only the attributes relevant to the object functionality are compared.</li>
- * <li>{@link #APPROXIMATIVE}: Only the attributes relevant to the object functionality are compared,
- * with some tolerance threshold on numerical values.</li>
- * <li>{@link #DEBUG}: Special mode for figuring out why two objects expected to be equal are not.</li>
+ * <li>{@link #STRICT} â All attributes of the compared objects shall be strictly equal.</li>
+ * <li>{@link #BY_CONTRACT} â Only the attributes published in the interface contract need to be compared.</li>
+ * <li>{@link #IGNORE_METADATA} â Only the attributes relevant to the object functionality are compared.</li>
+ * <li>{@link #APPROXIMATIVE} â Only the attributes relevant to the object functionality are compared,
+ * with some tolerance threshold on numerical values.</li>
+ * <li>{@link #DEBUG}: â Special mode for figuring out why two objects expected to be equal are not.</li>
* </ol>
*
* If two objects are equal at some degree of strictness <var>E</var>, then they should also
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java Sat Oct 20 11:00:57 2012
@@ -24,98 +24,80 @@ package org.apache.sis.util;
* coordinates calculation.
*
* {@section Conditions for equality}
- *
- * <table class="sis">
- * <tr><th colspan="2">{@link org.apache.sis.metadata.iso.MetadataEntity} subclasses</th></tr>
- * <tr><td>{@link ComparisonMode#STRICT STRICT}</td>
- * <td class="sep">Objects must be of the same class and all attributes must be equal, including {@code xlink}
- * and others {@linkplain org.apache.sis.metadata.iso.MetadataEntity#getIdentifiers() identifiers}.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}</td>
- * <td class="sep">The same attributes than the above {@code STRICT} mode must be equal,
- * but the metadata object don't need to be implemented by the same class
- * provided that they implement the same GeoAPI interface.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}</td>
- * <td class="sep">Only the attributes defined in the GeoAPI interfaces are compared.
- * The above-cited identifiers and {@code xlinks} attributes are ignored.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}</td>
- * <td class="sep">The same attributes than the above {@code IGNORE_METADATA} mode are compared,
- * but a slight (implementation dependant) difference is tolerated in floating point numbers.</td></tr>
- *
- *
- *
- * <tr><th class="hsep" colspan="2">{@link org.apache.sis.referencing.AbstractIdentifiedObject} subclasses</th></tr>
- * <tr><td>{@link ComparisonMode#STRICT STRICT}</td>
- * <td class="sep">Objects must be of the same class and all attributes must be equal.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}</td>
- * <td class="sep">The same attributes than the above {@code STRICT} mode must be equal,
- * but the referencing object don't need to be implemented by the same class
- * provided that they implement the same GeoAPI interface.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}</td>
- * <td class="sep">The
- * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getIdentifiers() identifiers},
- * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getAlias() aliases},
- * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getScope() scope},
- * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getDomainOfValidity() domain of validity} and
- * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getRemarks() remarks} are ignored because
- * they have no incidence on the coordinate values to be computed by
- * {@linkplain org.opengis.referencing.operation.ConcatenatedOperation coordinate operations}.
- * All other attributes that are relevant to coordinate calculations, must be equal.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}</td>
- * <td class="sep">The same attributes than the above {@code IGNORE_METADATA} mode are compared,
- * but a slight (implementation dependant) difference is tolerated in floating point numbers.</td></tr>
- *
- *
- *
- * <tr><th class="hsep" colspan="2">{@link org.apache.sis.referencing.operation.transform.AbstractMathTransform} subclasses
- * except {@link org.apache.sis.referencing.operation.transform.LinearTransform}</th></tr>
- * <tr><td>{@link ComparisonMode#STRICT STRICT}</td>
- * <td class="sep">Objects must be of the same class and all attributes must be equal, including the
- * {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform#getParameterValues()
- * parameter values}.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}</td>
- * <td class="sep">Synonymous to the {@code STRICT} mode, because there is no GeoAPI interfaces for the various
- * kind of math transforms.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}</td>
- * <td class="sep">Objects must be of the same class, but the parameter values can be different
- * if they are different way to formulate the same transform.
- * For example a {@code "Mercator (2SP)"} projection with a
- * {@linkplain org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#standardParallels
- * standard parallel} value of 60° produces the same results than a {@code "Mercator (1SP)"} projection with a
- * {@linkplain org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#scaleFactor scale factor}
- * value of 0.5</td></tr>
- *
- * <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}</td>
- * <td class="sep">The same attributes than the above {@code IGNORE_METADATA} mode are compared,
- * but a slight (implementation dependant) difference is tolerated in floating point numbers.</td></tr>
- *
- *
- *
- * <tr><th class="hsep" colspan="2">{@link org.apache.sis.referencing.operation.matrix.XMatrix} and
- * {@link org.apache.sis.referencing.operation.transform.LinearTransform} implementations</th></tr>
- * <tr><td>{@link ComparisonMode#STRICT STRICT}</td>
- * <td class="sep">Objects must be of the same class, matrixes must have the same size and all matrix
- * elements must be equal.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}</td>
- * <td class="sep">Matrixes must have the same size and all matrix elements must be equal,
- * but the matrixes are not required to be the same implementation class
- * (any {@link org.opengis.referencing.operation.Matrix} is okay).</td></tr>
- *
- * <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}</td>
- * <td class="sep">Synonymous to the {@code BY_CONTRACT} mode, because matrixes don't have metadata.</td></tr>
- *
- * <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}</td>
- * <td class="sep">The same attributes than the above {@code BY_CONTRACT} mode are compared,
- * but a slight (implementation dependant) difference is tolerated in floating point numbers.</td></tr>
- * </table>
+ * <ul>
+ * <li>{@link org.apache.sis.metadata.iso.MetadataEntity} subclasses
+ * <ul class="verbose">
+ * <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the same class
+ * and all attributes must be equal, including {@code xlink} and others
+ * {@linkplain org.apache.sis.metadata.iso.MetadataEntity#getIdentifiers() identifiers}.</li>
+ * <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â The same attributes than the above
+ * {@code STRICT} mode must be equal, but the metadata object don't need to be implemented
+ * by the same class provided that they implement the same GeoAPI interface.</li>
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} â Only the attributes defined
+ * in the GeoAPI interfaces are compared. The above-cited identifiers and {@code xlinks}
+ * attributes are ignored.</li>
+ * <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same attributes than the above
+ * {@code IGNORE_METADATA} mode are compared, but a slight (implementation dependant)
+ * difference is tolerated in floating point numbers.</li>
+ * </ul>
+ * </li>
+ * <li>{@link org.apache.sis.referencing.AbstractIdentifiedObject} subclasses
+ * <ul class="verbose">
+ * <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the same class
+ * and all attributes must be equal.</li>
+ * <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â The same attributes than the above
+ * {@code STRICT} mode must be equal, but the referencing object don't need to be
+ * implemented by the same class provided that they implement the same GeoAPI interface.</li>
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} â The
+ * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getIdentifiers() identifiers},
+ * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getAlias() aliases},
+ * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getScope() scope},
+ * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getDomainOfValidity() domain of validity} and
+ * {@linkplain org.apache.sis.referencing.crs.AbstractCRS#getRemarks() remarks}
+ * are ignored because they have no incidence on the coordinate values to be computed by
+ * {@linkplain org.opengis.referencing.operation.ConcatenatedOperation coordinate operations}.
+ * All other attributes that are relevant to coordinate calculations, must be equal.</li>
+ * <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same attributes than the above
+ * {@code IGNORE_METADATA} mode are compared, but a slight (implementation dependant)
+ * difference is tolerated in floating point numbers.</li>
+ * </ul>
+ * </li>
+ * <li>{@link org.apache.sis.referencing.operation.transform.AbstractMathTransform} subclasses
+ * except {@link org.apache.sis.referencing.operation.transform.LinearTransform}
+ * <ul class="verbose">
+ * <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the same class and all
+ * attributes must be equal, including the
+ * {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform#getParameterValues() parameter values}.</li>
+ * <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â Synonymous to the {@code STRICT} mode,
+ * because there is no GeoAPI interfaces for the various kind of math transforms.</li>
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} â Objects must be of the same
+ * class, but the parameter values can be different if they are different way to formulate
+ * the same transform. For example a {@code "Mercator (2SP)"} projection with a
+ * {@linkplain org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#standardParallels
+ * standard parallel} value of 60° produces the same results than a {@code "Mercator (1SP)"} projection with a
+ * {@linkplain org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#scaleFactor
+ * scale factor} value of 0.5</li>
+ * <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same attributes than the above
+ * {@code IGNORE_METADATA} mode are compared, but a slight (implementation dependant)
+ * difference is tolerated in floating point numbers.</li>
+ * </ul>
+ * </li>
+ * <li>{@link org.apache.sis.referencing.operation.matrix.XMatrix} and
+ * {@link org.apache.sis.referencing.operation.transform.LinearTransform} implementations
+ * <ul class="verbose">
+ * <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the same class, matrixes
+ * must have the same size and all matrix elements must be equal.</li>
+ * <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â Matrixes must have the same size
+ * and all matrix elements must be equal, but the matrixes are not required to be the
+ * same implementation class (any {@link org.opengis.referencing.operation.Matrix} is okay).</li>
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} â Synonymous to the
+ * {@code BY_CONTRACT} mode, because matrixes don't have metadata.</li>
+ * <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same attributes than the above
+ * {@code BY_CONTRACT} mode are compared, but a slight (implementation dependant)
+ * difference is tolerated in floating point numbers.</li>
+ * </ul>
+ * </li>
+ * </ul>
*
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-3.18)
@@ -125,21 +107,22 @@ package org.apache.sis.util;
public interface LenientComparable {
/**
* Compares this object with the given object for equality.
- * The strictness level is controlled by the second argument:
+ * The strictness level is controlled by the second argument,
+ * for stricter to more permissive values:
*
- * <table class="sis">
- * <tr><td>{@link ComparisonMode#STRICT STRICT}</td>
- * <td class="sep">All attributes of the compared objects shall be strictly equal.</td></tr>
- * <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}</td>
- * <td class="sep">Only the attributes published in the interface contract need to be compared.</td></tr>
- * <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}</td>
- * <td class="sep">Only the attributes relevant to the object functionality are compared.</td></tr>
- * <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}</td>
- * <td class="sep">Only the attributes relevant to the object functionality are compared,
- * with some tolerance threshold on numerical values.</td></tr>
- * <tr><td>{@link ComparisonMode#DEBUG DEBUG}</td>
- * <td class="sep">Special mode for figuring out why two objects expected to be equal are not.</td></tr>
- * </table>
+ * <ol>
+ * <li>{@link ComparisonMode#STRICT STRICT} â
+ * All attributes of the compared objects shall be strictly equal.</li>
+ * <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â
+ * Only the attributes published in the interface contract need to be compared.</li>
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} â
+ * Only the attributes relevant to the object functionality are compared.</li>
+ * <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â
+ * Only the attributes relevant to the object functionality are compared,
+ * with some tolerance threshold on numerical values.</li>
+ * <li>{@link ComparisonMode#DEBUG DEBUG} â
+ * special mode for figuring out why two objects expected to be equal are not.</li>
+ * </ol>
*
* @param other The object to compare to {@code this}.
* @param mode The strictness level of the comparison.
@@ -151,14 +134,28 @@ public interface LenientComparable {
/**
* Returns {@code true} if this object is strictly equals to the given object.
- * This method is typically implemented as below:
+ * This method is usually implemented as below:
*
* {@preformat java
- * return equals(other, ComparisonMode.STRICT);
+ * public boolean equals(Object other) {
+ * return equals(other, ComparisonMode.STRICT);
+ * }
* }
*
- * In SIS implementations, this method is typically {@code final} in order to ensure that
- * subclasses override the above {@link #equals(Object, ComparisonMode)} method instead.
+ * Implementors shall ensure that the following conditions hold. Unless the {@code equals}
+ * behavior is clearly documented in the interface javadoc (as for example in the Java
+ * collection framework), {@link ComparisonMode#STRICT} is the only reliable mode for
+ * this method implementation.
+ *
+ * <ul>
+ * <li>{@code A.equals(B)} implies {@code B.equals(A)};</li>
+ * <li>{@code A.equals(B)} and {@code B.equals(C)} implies {@code A.equals(C)};</li>
+ * <li>{@code A.equals(B)} implies {@code A.hashCode() == B.hashCode()};</li>
+ * </ul>
+ *
+ * This method is declared {@code final} in most SIS implementations for ensuring that
+ * subclasses override the above {@link #equals(Object, ComparisonMode)} method instead
+ * than this one.
*
* @param other The object to compare to {@code this}.
* @return {@code true} if both objects are strictly equal.
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerAdapter.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerAdapter.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerAdapter.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerAdapter.java Sat Oct 20 11:00:57 2012
@@ -43,7 +43,7 @@ import org.apache.sis.util.Debug;
* defined in terms of {@link #severe(String) severe} ⦠{@link #finest(String) finest} methods
* instead because external frameworks like <a href="http://commons.apache.org/logging/">Commons-logging</a>
* don't work with {@link LogRecord}, and sometime provides nothing else than convenience methods
- * equivalent to {@link #severe(String) severe} … {@link #finest(String) finest}.</p>
+ * equivalent to {@link #severe(String) severe} ⦠{@link #finest(String) finest}.</p>
*
* {@section Restrictions}
* Because the configuration is expected to be fully controlled by the external logging
Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XLink.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XLink.java?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XLink.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XLink.java Sat Oct 20 11:00:57 2012
@@ -46,7 +46,7 @@ import java.util.Objects;
*
* <blockquote><table class="sis">
* <tr>
- * <th> </th>
+ * <th>Â </th>
* <th width="14%">{@link XLink.Type#SIMPLE simple}</th>
* <th width="14%">{@link XLink.Type#EXTENDED extended}</th>
* <th width="14%">{@link XLink.Type#LOCATOR locator}</th>
@@ -54,36 +54,17 @@ import java.util.Objects;
* <th width="14%">{@link XLink.Type#RESOURCE resource}</th>
* <th width="14%">{@link XLink.Type#TITLE title}</th>
* </tr>
- * <tr align="center"><td><b>{@link #getType() type}</b></td>
- * <td>R</td><td>R</td><td>R</td><td>R</td><td>R</td><td>R</td>
- * </tr>
- * <tr align="center"><td><b>{@link #getHRef() href}</b></td>
- * <td>O</td><td> </td><td>R</td><td> </td><td> </td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getRole() role}</b></td>
- * <td>O</td><td>O</td><td>O</td><td> </td><td>O</td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getArcRole() arcrole}</b></td>
- * <td>O</td><td> </td><td> </td><td>O</td><td> </td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getTitle() title}</b></td>
- * <td>O</td><td>O</td><td>O</td><td>O</td><td>O</td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getShow() show}</b></td>
- * <td>O</td><td> </td><td> </td><td>O</td><td> </td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getActuate() actuate}</b></td>
- * <td>O</td><td> </td><td> </td><td>O</td><td> </td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getLabel() label}</b></td>
- * <td> </td><td> </td><td>O</td><td> </td><td>O</td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getFrom() from}</b></td>
- * <td> </td><td> </td><td> </td><td>O</td><td> </td><td> </td>
- * </tr>
- * <tr align="center"><td><b>{@link #getTo() to}</b></td>
- * <td> </td><td> </td><td> </td><td>O</td><td> </td><td> </td>
- * </tr></table></blockquote>
+ * <tr align="center"><td><b>{@link #getType() type}</b></td> <td>R</td><td>R</td><td>R</td><td>R</td><td>R</td><td>R</td></tr>
+ * <tr align="center"><td><b>{@link #getHRef() href}</b></td> <td>O</td><td>Â </td><td>R</td><td>Â </td><td>Â </td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getRole() role}</b></td> <td>O</td><td>O</td><td>O</td><td>Â </td><td>O</td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getArcRole() arcrole}</b></td> <td>O</td><td>Â </td><td>Â </td><td>O</td><td>Â </td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getTitle() title}</b></td> <td>O</td><td>O</td><td>O</td><td>O</td><td>O</td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getShow() show}</b></td> <td>O</td><td>Â </td><td>Â </td><td>O</td><td>Â </td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getActuate() actuate}</b></td> <td>O</td><td>Â </td><td>Â </td><td>O</td><td>Â </td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getLabel() label}</b></td> <td>Â </td><td>Â </td><td>O</td><td>Â </td><td>O</td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getFrom() from}</b></td> <td>Â </td><td>Â </td><td>Â </td><td>O</td><td>Â </td><td>Â </td></tr>
+ * <tr align="center"><td><b>{@link #getTo() to}</b></td> <td>Â </td><td>Â </td><td>Â </td><td>O</td><td>Â </td><td>Â </td></tr>
+ * </table></blockquote>
*
* When {@code xlink} attributes are found at unmarshalling time instead of an object definition,
* those attributes are given to the {@link ObjectLinker#resolve(Class, XLink)} method. Users can
Modified: sis/branches/JDK7/src/main/javadoc/stylesheet.css
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/src/main/javadoc/stylesheet.css?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/javadoc/stylesheet.css (original)
+++ sis/branches/JDK7/src/main/javadoc/stylesheet.css Sat Oct 20 11:00:57 2012
@@ -131,8 +131,8 @@ div.block ul {
}
ul.verbose li {
- margin-top: 6pt;
- margin-bottom: 6pt;
+ margin-top: 3pt;
+ margin-bottom: 3pt;
}
/*
Added: sis/branches/JDK7/src/site/apt/code-format.apt
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/src/site/apt/code-format.apt?rev=1400418&view=auto
==============================================================================
--- sis/branches/JDK7/src/site/apt/code-format.apt (added)
+++ sis/branches/JDK7/src/site/apt/code-format.apt Sat Oct 20 11:00:57 2012
@@ -0,0 +1,73 @@
+ -----------------------------
+ Code formatting
+ -----------------------------
+
+
+Code formatting
+
+ Apache SIS uses the standard Java conventions, except for the 80 characters line length restriction.
+ Other exceptions to the coding conventions may occur when tabular formatting can improve readability,
+ as in the example below:
+
+-----------------------
+if (x < xmin) xmin = x;
+if (x > xmax) xmax = x;
+if (y < ymin) ymin = y;
+if (y > ymax) ymax = y;
+-----------------------
+
+ Many mathematical operations in a two-dimensional space (or more) have symmetry.
+ Formatting the code in a way that emphase their symmetrical nature, for example
+ aligning identical terms in columns, can help to understand the overall pattern
+ and to identify bugs. The decision to use standard or tabular format is made on
+ a case-by-case basis. Of course, tabular format shall not be abused.
+
+
+* HTML in Javadoc
+
+ HTML tags and entities shall be used only when there is no equivalent Javadoc tag.
+ In addition to the standard Javadoc tags, a few
+ {{{./sis-build-helper/index.html}SIS-specific Javadoc tags}} are available.
+ For example:
+
+ * Instead of "<<<\<code\>>>>Foo<<<\</code\>>>>", use "<<<\{@code Foo\}>>>".
+
+ * Instead of "<<<a < b < c>>>", use "<<<\{@literal a \< b \< c\}>>>".
+
+ * Instead of "<<<\<pre\>>>>" for a Java listing, use "<<<\{@preformat java\}>>>"
+ (this Javadoc tag is specific to Apache SIS).
+
+
+** Paragraphs
+
+ Usages of the <<<\<p\>>>> tag should be relatively rare.
+ Do <<not>> use <<<\<p\>>>> for the first paragraph in a package, class or member documentation,
+ or for the first paragraph after a <<<\</ul\>>>>, <<<\</ol\>>>>, <<<\</table\>>>>,
+ <<<\</blockquote\>>>>, <<<\</pre\>>>>, <<<\{@preformat\}>>> or <<<\{@section\}>>> element.
+ The <<<\<p\>>>> tag shall be used only for separating a new paragraph from a previous one.
+ In such cases, <<<\<p\>>>> shall have a matching <<<\</p\>>>> tag at the paragraph end
+ in order to form valid HTML.
+
+
+** Styling
+
+ Avoid using HTML attributes other than <<<class>>> as much as possible.
+ Instead, rely on styling. Some HTML tags having a style definition in Apache SIS are:
+
+*---------------------------------+--------------------------------------------------------------------------------------------+
+|| HTML tag || Description ||
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<table class="sis"\>>>> | Table with a border, blue headers, light background and some space between columns. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<th class="hsep"\>>>> | In SIS tables, draw a line on the top border. Used for drawing table section separators. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<th class="sep"\>>>> | In SIS tables, draw a bright line on the left border. Used for drawing column separators. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<td class="sep"\>>>> | In SIS tables, draw a bright line on the left border. Used for drawing column separators. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<table class="compact"\>>>> | Table without border and no space between rows. Used for lists with columns alignment. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<ul\>>>> and <<<\<ol\>>>> | Default list styles without space between items (suitable for compact lists). |
+*---------------------------------+--------------------------------------------------------------------------------------------+
+| <<<\<ul class="verbose"\>>>> | A list style with space between items. Used for lists having verbose (multi-lines) items. |
+*---------------------------------+--------------------------------------------------------------------------------------------+
Modified: sis/branches/JDK7/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/src/site/apt/index.apt?rev=1400418&r1=1400417&r2=1400418&view=diff
==============================================================================
--- sis/branches/JDK7/src/site/apt/index.apt (original)
+++ sis/branches/JDK7/src/site/apt/index.apt Sat Oct 20 11:00:57 2012
@@ -24,7 +24,7 @@ The Apache SIS⢠library
* {{{./download.html}Downloading binaries}}
- * {{{http://builds.apache.org/job/sis-trunk/site/apidocs/index.html}Aggregated Javadoc}}
+ * {{{./apidocs/index.html}Aggregated Javadoc}}
* Developer Guide (English - translation to be provided later) ({{{./book/fr.xhtml}Français}})
@@ -37,6 +37,8 @@ The Apache SIS⢠library
* {{{./code-patterns.html}Recommended code patterns}}
+ * {{{./code-format.html}Code and Javadoc formatting}}
+
Apache SIS, Apache, the Apache feather logo, and the Apache SIS project logo are trademarks of
The Apache Software Foundation.