sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1635791 - in /sis/branches/JDK8/core: sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java
Date Fri, 31 Oct 2014 15:19:02 GMT
Author: desruisseaux
Date: Fri Oct 31 15:19:01 2014
New Revision: 1635791

URL: http://svn.apache.org/r1635791
Log:
Added documentation.

Modified:
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java?rev=1635791&r1=1635790&r2=1635791&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/MetadataUtilities.java
[UTF-8] Fri Oct 31 15:19:01 2014
@@ -89,6 +89,17 @@ public final class MetadataUtilities ext
      * or (in some case) zero. This method logs a warning if we are in process of (un)marshalling
a XML document,
      * or throw an exception otherwise.
      *
+     * <p><b>When to use:</b></p>
+     * <ul>
+     *   <li>This method is for setter methods that may be invoked by JAXB. Constructors
or methods ignored
+     *       by JAXB should use the simpler {@link org.apache.sis.util.ArgumentChecks} class
instead.</li>
+     *   <li>This method should be invoked only when ignoring the warning will not
cause information lost.
+     *       The stored metadata value may be invalid, but not lost.</li>
+     * </ul>
+     * <div class="note"><b>Note:</b> the later point is the reason why
problems during XML (un)marshalling
+     * are only warnings for this method, while they are errors by default for
+     * {@link org.apache.sis.xml.ValueConverter} (the later can not store the value in case
of error).</div>
+     *
      * @param  classe   The caller class.
      * @param  property The property name. Method name will be inferred by the usual Java
bean convention.
      * @param  strict   {@code true} if the value was expected to be strictly positive, or
{@code false} if 0 is accepted.
@@ -109,6 +120,17 @@ public final class MetadataUtilities ext
      * Convenience method invoked when an argument is outside the expected range of values.
This method logs
      * a warning if we are in process of (un)marshalling a XML document, or throw an exception
otherwise.
      *
+     * <p><b>When to use:</b></p>
+     * <ul>
+     *   <li>This method is for setter methods that may be invoked by JAXB. Constructors
or methods ignored
+     *       by JAXB should use the simpler {@link org.apache.sis.util.ArgumentChecks} class
instead.</li>
+     *   <li>This method should be invoked only when ignoring the warning will not
cause information lost.
+     *       The stored metadata value may be invalid, but not lost.</li>
+     * </ul>
+     * <div class="note"><b>Note:</b> the later point is the reason why
problems during XML (un)marshalling
+     * are only warnings for this method, while they are errors by default for
+     * {@link org.apache.sis.xml.ValueConverter} (the later can not store the value in case
of error).</div>
+     *
      * @param  classe   The caller class.
      * @param  property The property name. Method name will be inferred by the usual Java
bean convention.
      * @param  minimum  The minimal legal value.

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java?rev=1635791&r1=1635790&r2=1635791&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java
[UTF-8] Fri Oct 31 15:19:01 2014
@@ -151,6 +151,8 @@ public final class Supervisor extends St
 
     /**
      * Returns the operations impact, which is {@code INFO}.
+     *
+     * @return {@code INFO}.
      */
     @Override
     protected int getImpact(final MBeanOperationInfo info) {
@@ -159,6 +161,8 @@ public final class Supervisor extends St
 
     /**
      * Returns the localized description for this MBean.
+     *
+     * @return A localized description.
      */
     @Override
     protected String getDescription(final MBeanInfo info) {
@@ -167,6 +171,8 @@ public final class Supervisor extends St
 
     /**
      * Returns the localized description for the given constructor, attribute or operation.
+     *
+     * @return A localized description for the given attribute or operation.
      */
     @Override
     protected String getDescription(final MBeanFeatureInfo info) {
@@ -179,6 +185,7 @@ public final class Supervisor extends St
      * @param info     The constructor.
      * @param param    The constructor parameter.
      * @param sequence The parameter number (0 for the first parameter, 1 for the second,
etc.)
+     * @return A localized description for the specified constructor parameter.
      */
     @Override
     protected String getDescription(MBeanConstructorInfo info, MBeanParameterInfo param,
int sequence) {
@@ -191,6 +198,7 @@ public final class Supervisor extends St
      * @param info     The constructor.
      * @param param    The constructor parameter.
      * @param sequence The parameter number (0 for the first parameter, 1 for the second,
etc.)
+     * @return The name of the specified constructor parameter.
      */
     @Override
     protected String getParameterName(MBeanConstructorInfo info, MBeanParameterInfo param,
int sequence) {



Mime
View raw message