sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1599069 - in /sis/branches/JDK8: core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java src/main/javadoc/stylesheet.css
Date Sun, 01 Jun 2014 22:23:59 GMT
Author: desruisseaux
Date: Sun Jun  1 22:23:58 2014
New Revision: 1599069

URL: http://svn.apache.org/r1599069
Log:
Javadoc clarification attempt.

Modified:
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java
    sis/branches/JDK8/src/main/javadoc/stylesheet.css

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java?rev=1599069&r1=1599068&r2=1599069&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
[UTF-8] Sun Jun  1 22:23:58 2014
@@ -119,11 +119,11 @@ public class DefaultNameFactory extends 
     }
 
     /**
-     * Creates a namespace having the given name. Despite the "create" name, this method
tries
-     * to returns an existing instance when possible.
+     * Returns a namespace having the given name. Despite the "create" name, this method
tries to
+     * return an existing instance when possible. The namespace is characterized by the given
name,
+     * and optionally by the following properties:
      *
-     * <p>This method can receive an optional map of properties. Recognized entries
are:</p>
-     * <table class="sis">
+     * <blockquote><table class="sis">
      *   <caption>Recognized properties</caption>
      *   <tr>
      *     <th>Property name</th>
@@ -131,27 +131,31 @@ public class DefaultNameFactory extends 
      *   </tr>
      *   <tr>
      *     <td>{@code "separator"}</td>
-     *     <td>The separator to insert between
-     *     {@linkplain AbstractName#getParsedNames() parsed names} in that namespace.
-     *     For HTTP namespace, it is {@code "."}.
-     *     For URN namespace, it is typically {@code ":"}.</td>
+     *     <td>The separator to insert between {@linkplain AbstractName#getParsedNames()
parsed names}
+     *         in that namespace.</td>
      *   </tr>
      *   <tr>
      *     <td>{@code "separator.head"}</td>
-     *     <td>The separator to insert between the namespace and the
-     *     {@linkplain AbstractName#head() head}. For HTTP namespace, it is {@code "://"}.
-     *     For URN namespace, it is typically {@code ":"}. If this entry is omitted, then
-     *     the default is the same value than the {@code "separator"} entry.</td>
+     *     <td>The separator to insert between the namespace and the {@linkplain AbstractName#head()
head}.<br>
+     *         If omitted, then the default is the same value than {@code "separator"}.</td>
      *   </tr>
-     * </table>
+     * </table></blockquote>
+     *
+     * <div class="note"><b>Examples:</b>
+     * <ul>
+     *   <li>For URN namespace, {@code separator} = {@code ":"} is typically sufficient.</li>
+     *   <li>For HTTP namespace, {@code separator.head} = {@code "://"} and {@code
separator} = {@code "."}.</li>
+     * </ul></div>
      *
      * @param name
      *          The name of the namespace to be returned. This argument can be created using
-     *          <code>{@linkplain #createGenericName(NameSpace, CharSequence[]) createGenericName}(null,
parsedNames)</code>.
+     *          <code>{@linkplain #createGenericName(NameSpace, CharSequence[]) createGenericName}(null,
namespace)</code>.
      * @param properties
      *          An optional map of properties to be assigned to the namespace, or {@code
null} if none.
      *
      * @return A namespace having the given name and separator.
+     *
+     * @see Names#createLocalName(CharSequence, String, CharSequence)
      */
     @Override
     public NameSpace createNameSpace(final GenericName name, final Map<String,?> properties)
{
@@ -213,6 +217,8 @@ public class DefaultNameFactory extends 
      * @param  name The local name as a string or an international string.
      * @return The local name for the given character sequence.
      * @throws NullArgumentException If the {@code name} argument is null.
+     *
+     * @see Names#createLocalName(CharSequence, String, CharSequence)
      */
     @Override
     public LocalName createLocalName(final NameSpace scope, final CharSequence name) {

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java?rev=1599069&r1=1599068&r2=1599069&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java [UTF-8]
(original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/Names.java [UTF-8]
Sun Jun  1 22:23:58 2014
@@ -35,29 +35,37 @@ import static org.apache.sis.util.Argume
  *
  * {@section Relationship with Java Content Repository (JCR) names}
  * In the Java standard {@link javax.xml.namespace.QName} class and in the Java Content Repository
(JCR) specification,
- * a name is an ordered pair of (<var>Name space</var>, <var>Local part</var>)
strings. A JCR name can take two lexical
- * forms: <cite>expanded form</cite> and <cite>qualified form</cite>.
Those names are mapped to generic names as below:
+ * a name is an ordered pair of ({@code namespace}, {@code localPart}) strings. A JCR name
can take two lexical forms:
+ * <cite>expanded form</cite> and <cite>qualified form</cite>. Those
names are mapped to generic names as below:
  *
- * <blockquote><table class="sis">
+ * <blockquote><table class="sis" style="white-space: nowrap">
  *   <caption>Equivalence between JCR name and {@code GenericName}</caption>
  *   <tr>
  *     <th>JCR name</th>
- *     <th>GeoAPI equivalence</th>
+ *     <th class="sep" colspan="2">GeoAPI equivalence</th>
  *   </tr><tr>
- *     <td><code>ExpandedName  ::= '{' Namespace '}' LocalName</code></td>
- *     <td>{@code GenericName} with its {@linkplain AbstractName#scope() scope} set
to the JCR namespace.</td>
+ *     <td><code>ExpandedName ::= '{' Namespace '}' LocalPart</code></td>
+ *     <td class="sep"><code>GenericName.{@linkplain AbstractName#scope() scope()}.name().toString()</code></td>
+ *     <td>= JCR {@code Namespace}</td>
  *   </tr><tr>
- *     <td><code>QualifiedName ::= [Prefix ':'] LocalName</code></td>
- *     <td>{@code ScopedName} in the global namespace, with its {@linkplain DefaultScopedName#head()
head} or
- *         {@linkplain DefaultScopedName#path() path} set to the JCR prefix.</td>
+ *     <td></td>
+ *     <td class="sep"><code>GenericName.{@linkplain AbstractName#toString()
toString()}</code></td>
+ *     <td>= JCR {@code LocalPart}</td>
+ *   </tr><tr>
+ *     <td class="hsep"><code>QualifiedName ::= [Prefix ':'] LocalPart</code></td>
+ *     <td class="hsep sep"><code>ScopedName.{@linkplain AbstractName#scope()
scope()}</code></td>
+ *     <td class="hsep">= {@linkplain DefaultNameSpace#isGlobal() global namespace}</td>
+ *   </tr><tr>
+ *     <td></td>
+ *     <td class="sep"><code>ScopedName.{@linkplain DefaultScopedName#head()
head()}.toString()</code></td>
+ *     <td>= JCR {@code Prefix}</td>
+ *   </tr><tr>
+ *     <td></td>
+ *     <td class="sep"><code>ScopedName.{@linkplain DefaultScopedName#tail()
tail()}.toString()</code></td>
+ *     <td>= JCR {@code LocalPart}</td>
  *   </tr>
  * </table></blockquote>
  *
- * <div class="note"><b>Note:</b>
- * this {@code Names} convenience class takes the above-cited {@code NameSpace} and {@code
LocalName} strings
- * as a whole. However {@code GenericName} allows splitting those strings into smaller name
components.
- * If such finer grain control is desired, {@link DefaultNameFactory} can be used instead
of {@code Names}.</div>
- *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.5
  * @version 0.5
@@ -91,31 +99,36 @@ public final class Names extends Static 
      * The character sequences can be either {@link String} or {@link InternationalString}
instances.
      * Those character sequences are taken verbatim; they are <em>not</em> parsed
into their components.
      *
-     * <table class="sis">
+     * <div class="note"><b>Note:</b> it is possible to split the {@code
namespace} and {@code localPart}
+     * strings into smaller name components. If such finer grain control is desired, one
can use
+     * {@link DefaultNameFactory} instead of this {@code Names} class.</div>
+     *
+     * <div class="note"><b>Performance note:</b> this method is okay for
<em>casual</em> use. If many names need
+     * to be created in the same namespace, then {@link DefaultNameFactory#createLocalName(NameSpace,
CharSequence)}
+     * is more efficient since it allows to create the {@code NameSpace} object only once.</div>
+     *
+     * The following table shows where the strings given in argument will go:
+     *
+     * <blockquote><table class="sis">
      *   <caption>Mapping from arguments to name components</caption>
      *   <tr><th>Argument</th> <th>Mapped to</th></tr>
      *   <tr><td>{@code namespace}</td> <td><code>name.{@linkplain
DefaultLocalName#scope() scope()}.name().toString()</code></td></tr>
      *   <tr><td>{@code localPart}</td> <td><code>name.{@linkplain
DefaultLocalName#toString() toString()}</code></td></tr>
-     * </table>
+     * </table></blockquote>
      *
      * <div class="note"><b>Example:</b>
      * for a name created by {@code create("http://www.opengis.net/gml/srs/epsg.xml", "#",
"4326")}:
      * <blockquote><table class="compact" summary="Examples of return values for
a name built by this method.">
-     *   <tr><td>• <code>name.{@linkplain DefaultLocalName#scope() scope()}</code></td>
-     *       <td>returns the {@code "http://www.opengis.net/gml/srs/epsg.xml"} namespace.</td></tr>
      *   <tr><td>• <code>name.{@linkplain DefaultLocalName#toString()
toString()}</code></td>
      *       <td>returns the {@code "4326"} string.</td></tr>
+     *   <tr><td>• <code>name.{@linkplain DefaultLocalName#scope() scope()}</code></td>
+     *       <td>returns the {@code "http://www.opengis.net/gml/srs/epsg.xml"} namespace.</td></tr>
      *   <tr><td>• <code>name.{@linkplain DefaultLocalName#toFullyQualifiedName()
toFullyQualifiedName()}</code></td>
      *       <td>returns the {@code "http://www.opengis.net/gml/srs/epsg.xml#4326"}
name.
      *   <tr><td>• <code>{@linkplain #toExpandedString(GenericName)
toExpandedString}(name)</code></td>
      *       <td>returns the {@code "{http://www.opengis.net/gml/srs/epsg.xml}4326"}
string.</td></tr>
      * </table></blockquote></div>
      *
-     * <b>Performance note:</b> this method is okay for <em>casual</em>
use. If many names need to be created in the
-     * same namespace, a more efficient method is {@link DefaultNameFactory#createLocalName(NameSpace,
CharSequence)}
-     * for avoiding unnecessary creations of the same {@code NameSpace} object. The later
can be obtained by creating
-     * a first name using this {@code createLocalName} method, then invoke {@link GenericName#scope()}.
-     *
      * @param  namespace The namespace, or {@code null} for the global namespace.
      * @param  separator The separator between the namespace and the local part.
      * @param  localPart The name which is locale in the given namespace.

Modified: sis/branches/JDK8/src/main/javadoc/stylesheet.css
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/src/main/javadoc/stylesheet.css?rev=1599069&r1=1599068&r2=1599069&view=diff
==============================================================================
--- sis/branches/JDK8/src/main/javadoc/stylesheet.css (original)
+++ sis/branches/JDK8/src/main/javadoc/stylesheet.css Sun Jun  1 22:23:58 2014
@@ -71,6 +71,12 @@ table.sis tr th.hsep {
   border-top-color: darkgray;
 }
 
+table.sis tr td.hsep {
+  border-top-width: 1px;
+  border-top-style: solid;
+  border-top-color: darkgray;
+}
+
 table.sis tr th.sep {
   border-left-width: 1px;
   border-left-style: solid;



Mime
View raw message