[kepler-dev] Documentation updates

[Edward A. Lee]

Kevin:

Most of the time, the new documentation mechanism doesn't increase the size
of the MoML files at all.  Documentation for an actor defined in Java is in the
Java file as Javadoc fields.  The doclet Christopher wrote creates an DocML 
file
from the Java file.  It's a separate file.

When a user creates a model, the user can customize the documentation for
any actor, overriding the default documentation provided in the Java file.
This would commonly be done for composite actors, but would be less common
for atomic actors.  However, it might be useful for atomic actors too.
E.g., if you customize an Expression actor with specific input ports
and a complicated expression, you can override the default documentation
for the Expression actor to document this instance.

I think that the right place for instance documentation is in the MoML file.
This is where the instance is defined...

The right place for class documentation is with the class definition, which
for actors defined in Java is in the Java file.

Edward

At 04:03 PM 1/5/2006 -0600, Kevin Ruland wrote:

>Nandita,
>
>I think the end state is to have a deliverable .kar file which is 
>completely self contained.  That is it has the bytecode, the moml, and 
>supporting "static" information like documentation.  The format and 
>functionality of this beast has yet to be defined, but given that this 
>information is intended to be delivered as a unit I don't think there can 
>or should be any way for the end-user to update it.
>
>Storing the documentation in the moml might not be such a good idea.
>Given the current situation of parsing all the moml for all the actors on 
>Kepler startup, having the documentation in the moml cause the kepler 
>runtime memory requirements to be very much larger than they currently are.
>
>Since we plan on using classloaders to find the various resources for the 
>actors, I think it would be best if the documentation were a seperate file 
>distributed in the kar with the actor.  The moml would then contain the 
>name of the resource.
>
>Matt or Chad might have other insights which could allow this functionality.
>
>Kevin
>
>Nandita Mangal wrote:
>
>>Hi Kevin,
>>
>>As with the recent changes in the documentation infrastructure in Ptolemy 
>>( editing & storing the custum documentation  in a MOML file) , I was 
>>wondering if one can also implement the "GetDocumentation" feature in 
>>Kepler & store new results in the actor's moml file ? Could you also 
>>suggest  possible implementation changes/issues with the above structure 
>>in Kepler.
>>
>>Thanks!
>>Nandita.
>>
>>
>>Edward A. Lee wrote:
>>
>>>Ilkay:
>>>
>>>This is exactly what happens now... Drop in the Documentation attribute
>>>and double click on it, and you get a form for filling out documentation
>>>fields (overall description, author, documentation for each parameter
>>>and port, etc.).  The form is customized to the actor (you get fields for
>>>ports and parameters that exist...).
>>>
>>>Edward
>>>
>>>At 03:55 PM 1/2/2006 -0800, Ilkay Altintas wrote:
>>>

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