[kepler-dev] Documentation updates

[Edward A. Lee]

I agree with everything you say, and in fact have implemented what you are
recommended, with one exception...

In the actors that we have written, we have in fact written the Javadoc
documentation as user-level documentation (or at least tried to :-) ...
I'm sure there's room for improvement).  E.g., the class doc for the
Expression says:

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

What makes the Javadoc documentation not look like user-level documentation
is that they include a lot of irrelevant information (the inheritance hierarchy
is the very first thing you see, for example, and the method documentation
is irrelevant to most users).

What the doclet that Christopher wrote does is to extract from the Java
file the following:

   - The class documentation.
   - The author, version, rating tags.
   - The identity of the base class only, not the whole inheritance tree.
   - The documentation for ports and parameters.

It then generates a DocML file that is rendered by the tool I wrote very
much as user-level documentation.

As you suggest below, this information can be overridden to document a
specific instance.  That overridden information (and only that information)
gets stored with the instance in the MoML file.

Edward

At 07:57 PM 1/5/2006 -0600, Kevin Ruland wrote:

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

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