donaldp 2002/11/12 17:42:49
Modified: info/src/xdocs doclet.xml
Log:
Add documentation for all the javadoc tags
Revision Changes Path
1.2 +357 -1 jakarta-avalon-excalibur/info/src/xdocs/doclet.xml
Index: doclet.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/info/src/xdocs/doclet.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- doclet.xml 15 Sep 2002 01:42:30 -0000 1.1
+++ doclet.xml 13 Nov 2002 01:42:49 -0000 1.2
@@ -11,9 +11,365 @@
using javadoc tags. This markup will then be read by the
<a href="tasks.html#infodoclet"><code>infodoclet</code></a>
task and used to generate the Info descriptors.</p>
+ <p>There are several advantages of using this approach.</p>
+ <ul>
+ <li>its a lot faster than writing Info files by hand.</li>
+ <li>its harder to make mistakes, since much of the data
+ required for the info descriptors is parsed out of the
+ source code</li>
+ <li>useful defaults can be used by reading the standard
+ javadoc.</li>
+ <li>Upgrades to descriptors can be transparent.</li>
+ </ul>
</section>
<section name="Doclet Tag Types">
- </section>
+ <p>The following tags are defined;</p>
+ <ul>
+ <li><a href="#avalon.component">avalon.component</a></li>
+ <li><a href="#avalon.service">avalon.service</a></li>
+ <li><a href="#avalon.logger">avalon.logger</a></li>
+ <li><a href="#avalon.context">avalon.context</a></li>
+ <li><a href="#avalon.entry">avalon.entry</a></li>
+ <li><a href="#avalon.dependency">avalon.dependency</a></li>
+ <li><a href="#avalon.configuration">avalon.configuration</a></li>
+ <li><a href="#avalon.parameters">avalon.parameters</a></li>
+ </ul>
+ <subsection name="avalon.component">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Class level javadocs</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Marks the class as a Avalon component.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.component tag does not currently
+ support any parameters.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+package com.biz;
+
+/**
+ * This is an Avalon component.
+ *
+ * @avalon.component
+ */
+public class MyComponent
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <component type="com.biz.MyComponent">
+]]></source>
+ </subsection>
+ <subsection name="avalon.service">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Class level javadocs</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the set of services that a component is
+ capable of providing.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.service has a single parameter named
+ "type" which specifies the type of service (ie the
+ interface classname) that the component
+ supports.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+package com.biz;
+
+import com.biz.services.MyService1;
+/**
+ * This is an Avalon component.
+ *
+ * @avalon.service type="MyService1"
+ * @avalon.service type="MyService2"
+ */
+public class MyComponent
+ implements MyService1, MyService2, SomeOtherInterface
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <services>
+ <service type="com.biz.services.MyService1"/>
+ <service type="com.biz.MyService2"/>
+ </services>
+]]></source>
+ </subsection>
+ <subsection name="avalon.logger">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the LogEnabled.enableLogging(Logger)
+ method.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the loggers that the component will
+ use.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.logger tag takes one parameter
+ "name" that specifies the name of the logger
+ to use. If not specified the logger defualts to
+ an empty ("") name.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.logger
+ * @avalon.logger name="auth"
+ */
+public void enableLogging( Logger logger )
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <loggers>
+ <logger/>
+ <logger name="auth"/>
+ </loggers>
+]]></source>
+ </subsection>
+ <subsection name="avalon.context">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the
+ Contextualizable.contextualize(Context)
+ method.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the type of the context expected.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.context tag takes one parameter named
+ "type" that specifies the expected type of the
+ context.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.context type="BlockContext"
+ */
+public void contextualize( Context context )
+ throws ContextException
+{
+ m_context = (BlockContext)context;
+}
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <context type="org.apache.avalon.phoenix.BlockContext">
+ ...
+ </context>
+]]></source>
+ </subsection>
+ <subsection name="avalon.entry">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the
+ Contextualizable.contextualize(Context)
+ method.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the way an item is exposed in the
+ context.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.entry has three parameters;
+ <em>key</em>, <em>type</em> and <em>optional</em>.
+ The key parameter specifies the key that is used
+ to look up entry in context. The type specifies
+ the type of the object in the entry. The optional
+ parameter defaults to false but if set to true
+ will indicate that the entry need not be
+ provided.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.entry key="component.name" type="String"
+ * @avalon.entry key="component.classloader" type="ClassLoader"
+ * @avalon.entry key="mbean.server" type="MBeanServer" optional="true"
+ */
+public void contextualize( Context context )
+ throws ContextException
+{
+ m_name = (String)context.get( "component.name" );
+ m_classLoader = (ClassLoader)context.get( "component.classloader" );
+
+ try
+ {
+ m_mBeanServer = (MBeanServer)context.get( "mbean.server" );
+ }
+ catch( final ContextException ce )
+ {
+ //Not present so lets not be managed by JMX
+ }
+}
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <context>
+ <entry key="component.name"
+ type="java.lang.String"/>
+ <entry key="component.classloader"
+ type="java.lang.ClassLoader"/>
+ <entry key="mbean.server"
+ type="javax.management.MBeanServer"
+ optional="true"/>
+ </context>
+]]></source>
+ </subsection>
+ <subsection name="avalon.dependency">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the
+ Composable.compose(ComponentManager) or
+ Serviceable.service(ServiceManager)
+ methods.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the dependencies on other
+ services.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.dependency has three parameters;
+ <em>key</em>, <em>type</em> and <em>optional</em>.
+ The key parameter specifies the key that is used
+ to look up service and defaults to the type name
+ if not specified. The type specifies the type of
+ the service. The optional parameter defaults to
+ false but if set to true will indicate that the
+ service need not be provided.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.dependency type="Store"
+ * @avalon.dependency key="Store/Spool" type="Store"
+ * @avalon.dependency type="Monitor" optional="true"
+ */
+public void service( ServiceManager sm )
+ throws ServiceException
+{
+ m_store = (Store)sm.get( Store.ROLE );
+ m_spoolStore = (Store)sm.lookup( Store.ROLE + "/Spool" );
+ if( sm.hasService( Monitor.ROLE ) )
+ {
+ m_monitor = (Monitor)sm.get( Monitor.ROLE );
+ }
+}
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+<dependencies>
+ <dependency type="org.apache.avalon.services.Store" />
+ <dependency key="org.apache.avalon.services.Store/Spool"
+ type="org.apache.avalon.services.Store" />
+ <dependency type="org.apache.avalon.services.Monitor" optional="true"/>
+</dependencies>
+]]></source>
+ </subsection>
+ <subsection name="avalon.configuration">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the
+ Configurable.configure(Configuration)
+ method.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the schema which the configuration
+ object must conform to.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.configuration has one parameter;
+ <em>schema</em>. "schema" indicates the location
+ of the schema definition file for configuration.
+ Several different schema types are supported such
+ as W3C XMLSchema, DTD, Relax NG etc. If the
+ parameter is unspecified it defaults to
+ "{componentname}-schema.xml".</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.configuration
+ */
+public void configure( Configuration config )
+ throws ConfigurationException
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <configuration schema="MyComponent-schema.xml"/>
+]]></source>
+ </subsection>
+ <subsection name="avalon.parameters">
+ <table>
+ <tr>
+ <td>Scope</td>
+ <td>Javadocs on the
+ Parameterizable.parameterize(Parameters)
+ method.</td>
+ </tr>
+ <tr>
+ <td>Purpose</td>
+ <td>Specifies the schema which the parameters
+ object must conform to.</td>
+ </tr>
+ <tr>
+ <td>Parameters</td>
+ <td>The avalon.parameters has one parameter;
+ <em>schema</em>. "schema" indicates the location
+ of the schema definition file for parameters.
+ If the parameter is unspecified it defaults to
+ "{componentname}-schema.xml". Note that currently
+ there is no supported schema for parameters
+ objects.</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+<source><![CDATA[
+/**
+ * @avalon.parameters schema="Foo.xml"
+ */
+public void parameterize( Parameters parameters )
+ throws ParametersException
+]]></source>
+ <p>Will produce the following part of xml info descriptor:</p>
+<source><![CDATA[
+ <parameters schema="Foo.xml"/>
+]]></source>
+ </subsection>
+ </section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:avalon-cvs-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@;jakarta.apache.org>
