[kepler-dev] Documentation infrastructure
Edward A. Lee
eal at eecs.berkeley.edu
Wed Dec 28 15:33:21 PST 2005
I'm checking in to the Ptolemy CVS repository a documentation infrastructure
that seems to be pretty usable already, although further work is needed to
create the doclets that generate the doc files.
The attached images show (1) customized documentation for an instance,
showing how some fields are inherited from the base class and some are
overridden in the instance. (2) the documentation for the class, obtained
by following the link at the lower right of the instance documentation.
Currently, you can create custom documentation for any actor (including
a top-level model), by right clicking and selecting Documentation->
Customize Documentation. The custom documentation is stored in the
MoML file for the model.
Documentation for Java classes is found in files that are XML file following
a simple schema that I call DocML. You can currently create these files
by hand, and if you put them in the $PTII/doc/codeDoc tree (next to the
Javadoc documentation files), then they will be found automatically.
You can also directly open using them using File->Open. I've attached such
a file for the Expression actor.
The next (and final) step is to write a doclet to create these DocML files
from the Javadoc information. Any volunteers to do this?
Edward
------------
Edward A. Lee
Professor, Chair of the EE Division, Associate Chair of EECS
231 Cory Hall, UC Berkeley, Berkeley, CA 94720
phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal
-------------- next part --------------
A non-text attachment was scrubbed...
Name: instanceDoc.gif
Type: application/octet-stream
Size: 27606 bytes
Desc: not available
URL: <http://mercury.nceas.ucsb.edu/kepler/pipermail/kepler-dev/attachments/20051228/92f2cefc/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: classDoc.gif
Type: application/octet-stream
Size: 27062 bytes
Desc: not available
URL: <http://mercury.nceas.ucsb.edu/kepler/pipermail/kepler-dev/attachments/20051228/92f2cefc/attachment-0001.obj>
-------------- next part --------------
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE doc PUBLIC "-//UC Berkeley//DTD DocML 1//EN"
"http://ptolemy.eecs.berkeley.edu/xml/dtd/DocML_1.dtd">
<doc name="Expression" class="ptolemy.actor.lib.Expression">
<description>
On each firing, evaluate an expression that may include references
to the inputs, current time, and a count of the firing. The ports
are referenced by the identifiers that have the same name as the
port. To use this class, instantiate it, then add ports (instances
of TypedIOPort). In vergil, you can add ports by right clicking on
the icon and selecting "Configure Ports". In MoML you can add
ports by just including ports of class TypedIOPort, set to be
inputs, as in the following example:
<p>
<pre>
&lt;entity name="exp" class="ptolemy.actor.lib.Expression"&gt;
&lt;port name="in" class="ptolemy.actor.TypedIOPort"&gt;
&lt;property name="input"/&gt;
&lt;/port&gt;
&lt;/entity&gt;
</pre>
<p> This actor is type-polymorphic. The types of the inputs can be
arbitrary and the types of the outputs are inferred from the
expression based on the types inferred for the inputs.
<p> The <i>expression</i> parameter specifies an expression that
can refer to the inputs by name. By default, the expression is
empty, and attempting to execute the actor without setting it
triggers an exception. This actor can be used instead of many of
the arithmetic actors, such as AddSubtract, MultiplyDivide, and
TrigFunction. However, those actors will be usually be more
efficient, and sometimes more convenient to use.
<p> The expression language understood by this actor is the same as
<a href="../../../../expressions.htm">that used to set any
parameter value</a>, with the exception that the expressions
evaluated by this actor can refer to the values of inputs, and to
the current time by the identifier name "time", and to the current
iteration count by the identifier named "iteration."
<p> This actor requires its all of its inputs to be present. If
inputs are not all present, then an exception will be thrown.
<p> NOTE: There are a number of limitations in the current
implementation. Primarily, multiports are not supported.
</description>
<author>Xiaojun Liu, Edward A. Lee, Steve Neuendorffer</author>
<version>$Id: Expression.java,v 1.120 2005/10/28 19:20:13 cxh Exp $</version>
<since>Ptolemy II 0.2</since>
<proposedRating>Green (neuendor)</proposedRating>
<acceptedRating>Green (neuendor)</acceptedRating>
<port name="output">The output port.</port>
<property name="expression">The expression that is evaluated to produce the output.</property>
</doc>
More information about the Kepler-dev
mailing list