[kepler-dev] Actor documentation

[Edward A. Lee]

In the middle of the night, in lieu of sleeping, I prototyped
a documentation mechanism in Ptolemy II that reflects some of the
ideas I proposed by email about a week ago.  I would like to coordinate
with whoever is working on Kepler's documentation infrastructure for
actors and models (Ilkay?) to make sure we get something really good.
The attached gif file shows a sample page that you get (in my private
tree) when you select "Get Documention" from the context menu.

At the upper left, it displays the icon for the actor on which you
select it (even a custom icon), displays all the port names, and
also all the parameter values (although in this example, this actor
has no parameters).

At the upper right it displays the actor documentation, which by
default comes from a file that I propose be generated by a doclet
from the Java file.  The particular file being used is given below,
from which you can infer what sort of DTD I have in mind.

The intended behavior is as follows:

Right click->Get Documentation does (or will do) the following:

   - Look first for a ConfigurableAttribute in the actor that
     contains the documentation.

   - If there is no such attribute, then look for a doc file
     (an XML file like the one below) that is generated from
     Java file by a doclet.

   - If there is no such doc file, look for a doc file for the
     base class.

I still have to work out how this will work with the actor-oriented
class system...

The documentation itself is (or will be) constructed by
blending information as follows:

   - Get as much information from the instance as is provided
   - For missing information, try the doc file generated
     from the doclet.
   - For information still missing, try the doc file for the
     base class.

The pieces of information include the class documentation
and documentation for each of the parameters and ports.

My intent is then to add a context menu command "Edit Documentation"
that will permit overriding any of the specific pieces of information
that you wish to override.

Comments?  Collaborators?

Edward

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE plot PUBLIC "-//UC Berkeley//DTD DocML 1//EN"
     "http://ptolemy.eecs.berkeley.edu/xml/dtd/DocML_1.dtd">
<doc name="DotProduct">
<description>
  Compute the dot product of two arrays or matrices. This actor has two
  input ports, from which it receives two ArrayTokens or two Matrix
  Tokens. The elements of the ArrayTokens or MatrixTokens must be of
  type ScalarToken. The output is the dot product of the two arrays or
  matrices.
  &lt;p&gt; This actor requires that each input port have a token upon
  firing. On each firing, it produces exactly one token, which is of
  type ScalarToken.
  &lt;/p&gt;
</description>
<author>Jeff Tsay, Paul Whitaker, Adam Cataldo</author>
<version>$Id: DotProduct.java,v 1.39 2005/07/08 19:58:43 cxh Exp $</version>
<since>Ptolemy II 1.0</since>
<proposedRating>Yellow (pwhitake)</proposedRating>
<acceptedRating>Red (acataldo)</acceptedRating>
<port name="input1">
The first input port. This has type ArrayToken. The elements of
the ArrayToken must be of type ScalarToken.
</port>
<port name="input2">
The second input port. This has type ArrayToken. The elements of
the ArrayToken must be of type ScalarToken.
</port>
<port name="output">
The output port, which has type ScalarToken.
</port>
</doc>



------------
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: proposedDocDisplay.gif
Type: application/octet-stream
Size: 20999 bytes
Desc: not available
Url : http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20051215/9e3dab83/proposedDocDisplay-0001.obj