[prev in list] [next in list] [prev in thread] [next in thread]
List: avalon-dev
Subject: [Patch] Javadoc fixes for Avalon framework
From: Mark Woon <morpheus () SMI ! Stanford ! EDU>
Date: 2002-02-28 1:04:31
[Download RAW message or body]
Attached is a patch to clarify some documentation:
- deprecate AbstractLoggable
- get both "Developing with Avalon" document and Javadocs to state that
Parameterizable and Configurable are not compatible (they were contradicting
each other)
There are a bunch of warnings about the @pre and @post tags in the Javadocs for
org.avalon.apache.framework.configuration.*. Is there an Avalon specific
doclet that's supposed to deal with these tags? If not, should they be
removed?
-Mark
["framework-diffs.txt" (text/plain)]
Index: src/java/org/apache/avalon/framework/logger/AbstractLoggable.java
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/java/org/apache/avalon/framework/logger/AbstractLoggable.java,v
retrieving revision 1.7
diff -u -r1.7 AbstractLoggable.java
--- src/java/org/apache/avalon/framework/logger/AbstractLoggable.java 11 Dec 2001 \
09:00:46 -0000 1.7
+++ src/java/org/apache/avalon/framework/logger/AbstractLoggable.java 28 Feb 2002 \
01:02:33 -0000 @@ -10,6 +10,8 @@
/**
* Utility class to allow construction of easy components that will perform logging.
*
+ * @deprecated Use {@link AbstractLogEnabled} instead.
+ *
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
*/
public abstract class AbstractLoggable
Index: src/java/org/apache/avalon/framework/logger/Loggable.java
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/java/org/apache/avalon/framework/logger/Loggable.java,v
retrieving revision 1.6
diff -u -r1.6 Loggable.java
--- src/java/org/apache/avalon/framework/logger/Loggable.java 11 Dec 2001 09:00:46 \
-0000 1.6
+++ src/java/org/apache/avalon/framework/logger/Loggable.java 28 Feb 2002 01:02:33 \
-0000 @@ -11,7 +11,7 @@
* Components that need to log can implement this interface to
* be provided Loggers.
*
- * @deprecated Use LogEnabled instead.
+ * @deprecated Use {@link LogEnabled} instead.
*
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
* @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
Index: src/java/org/apache/avalon/framework/parameters/Parameterizable.java
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/java/org/apache/avalon/framework/parameters/Parameterizable.java,v
retrieving revision 1.4
diff -u -r1.4 Parameterizable.java
--- src/java/org/apache/avalon/framework/parameters/Parameterizable.java 11 Dec 2001 \
09:00:47 -0000 1.4
+++ src/java/org/apache/avalon/framework/parameters/Parameterizable.java 28 Feb 2002 \
01:02:33 -0000 @@ -8,11 +8,19 @@
package org.apache.avalon.framework.parameters;
/**
- * Components should implement this interface if they wish to
- * be provided with parameters during startup. This interface
- * will be called after Composable.compose() and before
- * Initializable.initialize(). It is incompatible with the
- * Configurable interface.
+ * Components should implement this interface if they wish to
+ * be provided with parameters during startup.
+ * <p>
+ * The Parameterizable interface is a light-weight alternative to the
+ * {@link org.apache.avalon.framework.configuration.Configurable}
+ * interface. As such, the <code>Parameterizable</code> interface and
+ * the <code>Configurable</code> interface are <strong>not</strong>
+ * compatible.
+ * </p><p>
+ * This interface will be called after
+ * <code>Composable.compose()</code> and before
+ * <code>Initializable.initialize()</code>.
+ * </p>
*
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
*/
Index: src/java/org/apache/avalon/framework/parameters/Parameters.java
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/java/org/apache/avalon/framework/parameters/Parameters.java,v
retrieving revision 1.20
diff -u -r1.20 Parameters.java
--- src/java/org/apache/avalon/framework/parameters/Parameters.java 30 Dec 2001 \
06:26:39 -0000 1.20
+++ src/java/org/apache/avalon/framework/parameters/Parameters.java 28 Feb 2002 \
01:02:34 -0000 @@ -17,14 +17,29 @@
import org.apache.avalon.framework.configuration.ConfigurationException;
/**
- * The Parameters represents a set of key-value pairs.
- * Each value stored in Parameters has a key.
- * This class is similar to java.util.Properties with convenience methods
- * to access property values by type.
+ * The <code>Parameters</code> class represents a set of key-value
+ * pairs.
* <p>
- * <strong>Note, this class is not thread safe by default.</strong> If you
- * require thread safety please synchronize write access to this class to
- * prevent potential data corruption.
+ * The <code>Parameters</code> object provides a mechanism to obtain
+ * values based on a <code>String</code> name. There are convenience
+ * methods that allow you to use defaults if the value does not exist,
+ * as well as obtain the value in any of the same formats that are in
+ * the {@link Configuration} interface.
+ * </p><p>
+ * While there are similarities between the <code>Parameters</code>
+ * object and the java.util.Properties object, there are some
+ * important semantic differences. First, <code>Parameters</code> are
+ * <i>read-only</i>. Second, <code>Parameters</code> are easily
+ * derived from {@link Configuration} objects. Lastly, the
+ * <code>Parameters</code> object is derived from XML fragments that
+ * look like this:
+ * <pre><code>
+ * <parameter name="param-name" value="param-value" />
+ * </code></pre>
+ * </p><p>
+ * <strong>Note: this class is not thread safe by default.</strong> If you
+ * require thread safety please synchronize write access to this class to
+ * prevent potential data corruption.
* </p>
*
* @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
Index: src/java/org/apache/avalon/framework/service/Serviceable.java
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/java/org/apache/avalon/framework/service/Serviceable.java,v
retrieving revision 1.1
diff -u -r1.1 Serviceable.java
--- src/java/org/apache/avalon/framework/service/Serviceable.java 21 Feb 2002 \
04:36:35 -0000 1.1
+++ src/java/org/apache/avalon/framework/service/Serviceable.java 28 Feb 2002 \
01:02:34 -0000 @@ -21,7 +21,6 @@
* can be considered valid.
*
* @see org.apache.avalon.framework.service.ServiceManager
- * @see org.apache.avalon.framework.service.ServiceResolver
*
* @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
* @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
Index: src/xdocs/developing/framework.xml
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/xdocs/developing/framework.xml,v
retrieving revision 1.12
diff -u -r1.12 framework.xml
--- src/xdocs/developing/framework.xml 18 Feb 2002 16:55:35 -0000 1.12
+++ src/xdocs/developing/framework.xml 28 Feb 2002 01:02:34 -0000
@@ -211,16 +211,13 @@
</para>
</listitem>
<listitem>
- <para>
- <function>configure</function>
- [<classname>Configurable</classname>]
- </para>
- </listitem>
- <listitem>
- <para>
- <function>parameterize</function>
- [<classname>Parameterizable</classname>]
- </para>
+ <para>
+ <function>configure</function>
+ [<classname>Configurable</classname>]
+ <emphasis>or</emphasis>
+ <function>parameterize</function>
+ [<classname>Parameterizable</classname>]
+ </para>
</listitem>
<listitem>
<para>
@@ -473,7 +470,7 @@
<title>Configuration</title>
<para>
This group of interfaces describes the concern area of configuration.
- If there are any problems like required
+ If there are any problems, such as required
<classname>Configuration</classname> elements that are missing, then
you may throw a <classname>ConfigurationException</classname>.
</para>
@@ -669,10 +666,8 @@
</para>
<para>
The contract is that this is called once during the lifecycle of
- the Component. Usually this interface is used in lieu of the
- <classname>Configurable</classname> interface, however if both are
- used, the <function>parameterize</function> method is called after
- the <function>configure</function> method.
+ the Component. This interface is not compatible with the
+ <classname>Configurable</classname> interface.
</para>
</section>
<section>
Index: src/xdocs/framework/changes.xml
===================================================================
RCS file: /home/cvspublic/jakarta-avalon/src/xdocs/framework/changes.xml,v
retrieving revision 1.14
diff -u -r1.14 changes.xml
--- src/xdocs/framework/changes.xml 31 Jan 2002 17:12:53 -0000 1.14
+++ src/xdocs/framework/changes.xml 28 Feb 2002 01:02:34 -0000
@@ -27,7 +27,7 @@
<action dev="LM" type="update">
Update build to have a "compress.jars" property (defaults to
true by default).
- <action>
+ </action>
</release>
<release version="4.1.1" date="December 21, 2001">
<action dev="BL" type="fix">
--
To unsubscribe, e-mail: <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic