[kepler-dev] Actor documentation

[Ilkay Altintas]

Hi Edward,

On Dec 15, 2005, at 8:45 PM, Edward A. Lee wrote:

>
> 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.

Many thanks for looking into this.  It would be really great to  
consolidate Ptolemy and Kepler documentation efforts. I think this will  
save a lot of headache later.


> 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).

This is nicer than, but similar to the format that Xiaowen and I worked  
on generating from the Javadoc.

>
> 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.

When we tried this approach, it didn't scale to all the entities we'd  
like to be documented. It would be great if you have any ideas how we  
could combine it with the non-Java classes, workflows, packages, etc.  
We could probably have a hybrid approach using this and docbook-style  
hand-written structured documentation approach we take right now.

> 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...

Looking forward to hear your  thoughts on this.


> 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.
>

This is more like a hybrid approach combining the javadoc and   
hand-written documentation, right?


> 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.

This sounds like a good idea. I need to ask the rest of Kepler  
developers in terms of usability. (Laura: any comments?)

-ilkay

>
> 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   
> <proposedDocDisplay.gif>_______________________________________________
> Kepler-dev mailing list
> Kepler-dev at ecoinformatics.org
> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler- 
> dev