[kepler-dev] Documentation updates

[Kevin Ruland]

Edward,

I think I'm understanding.  It might be best for Matt to clarify for me 
as well.  I'm just going to think on line.

There are two different things which need to be distinguished.  An 
Actor's prototype definition, and an instance of an actor.  The 
prototype actor is the one as distributed with the system - with the 
default documentation, parameter settings, etc.  When the user drags 
this actor into the workspace, he is making an instance of the actor.  
This instance begins its life with default parameter settings, port 
annotations, name, etc.  When the user then changes the parameters and 
saves, the changes to the parameters are captured in the workspace moml 
file, correct?  It does not change the default parameters assigned to 
the next instance of the actor.

Along these lines, I'm thinking that all the mutable information about 
an instance of an actor needs to be collected together.  So the 
documentation, port annotations, text label, etc all should be stored 
similarly.

I was thinking originally only of the main class level documentation - 
that is, a general description of the transformation performed by the 
little box, description of input constraints etc.  This would be more 
like the class level documentation but not as low level as javadoc which 
would probably be less useful and more confusing to some.  This 
documentation should not be allowed to change.

However, the way a particular actor is used in a workflow could benefit 
from additional documentation.  This documentation could capture what 
specific function the actor provides in the greater context of the 
problem being solved.  I believe that Dan in the past has use some text 
annotations for this.

I think I've only looked at the two extremes:  Default actor ....  
instance of actor in workflow.  I have not considered the case of making 
a specific actor which is intended to be reused.   Chad has already come 
up with a scheme which allows the user to take an instance of an actor 
(with parameter changes, and presumably docuementation changes) and drag 
it back into the actor tree.  This action would allow the user to use 
this actor instance as a prototype for future workflows.  I don't know 
how this action is accomplished, or if it is currently functionaly, but 
the prototype created would then be "read-only" in the same sense as the 
original it was based on.

Kevin


Edward A. Lee wrote:

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