[kepler-dev] Documentation updates

Kevin Ruland kruland at ku.edu
Fri Jan 6 08:55:34 PST 2006


You have thought of everything.  It seems that there should be no 
difficulty here.  I do have some questions:  The DocML file, is it a 
seperate file or is it embedded in the actor's moml file?  Is it 
possible to call the rendering tool using an open InputStream rather 
than a filename?  This will enable us to track down the DocML file using 

BTW - I do have to agree that well written class documentation is useful 
to both developers and users.  My experience with reading and writing 
javadoc is it tends to be quite brief and sometimes very confusing.  
Let's hope at least this piece of javadoc can be well written.


Edward A. Lee wrote:

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

More information about the Kepler-dev mailing list