[kepler-dev] Request for adding documentation on Kepler Actors

Thu Dec 1 14:34:41 PST 2005

While I realize I'm chiming in late, not having participated in the
previous discussions, I confess that I'm skeptical...

I think that extracting the documentation from the Javadoc in the source
file would certainly work well for the vast majority of the actors in the
Ptolemy II library.  I agree that this is probably less true of many Kepler
actors, and also certainly not true of composite actors.

However, it wouldn't be hard to have a design that got the best of both
worlds. Default behavior is to present Javadoc-extracted information.
Then make this easy to override, and to store the override in MoML.

E.g.,

   - Create a javadoc tool that runs with the build that generates
     a doc file for each actor defined in java. That doc file could
     reside in the tree next to the source file.

   - Create a configurable attribute that can contain the same
     information as the what would be in the doc file.

   - Modify the GUI "get Documentation" command to first look for
     this configurable attribute, and if it is absent, look for
     the doc file.

It would then be easy to add the following:

   - Create a GUI command "edit Documentation" that would generate
     a template of the XML documentation information (containing
     information about whatever ports and parameters are present).

Then you could override the default (Javadoc-generated) documentation
with something more specific.

One downside of including documentation in the MoML file is that when
you create multiple instances of an actor, they will likely each have
a copy of the documentation. If you have a lot of instances, this will
result in many copies, which will bloat the MoML files...

Edward

At 09:47 AM 12/1/2005 -0900, Matt Jones wrote:
>And I'd like to re-emphasize the last point in my prior email -- Java code 
>does not exist for composite actors (nor specialied atomics such as the 
>RExpression or WebService actors), and these need to be documented 
>too.  We decided it was better to have all documentation in the MoML than 
>to have some in java source and some in another location (for composites, etc).
>
>Matt
>
>Ilkay Altintas wrote:
>>Hi Xiaowen,
>>Below is some further comments on why we have backed away from the
>>javadoc solution that you and I have worked on.
>>On Dec 1, 2005, at 10:32 AM, xiaowen wrote:
>>
>>>I've missed Kepler discussions about this, so I apologize in advance if
>>>what I say below has already been discussed. :)  For what it's worth  ...
>>>
>>>At 09:27 01.12.2005, Matt Jones wrote:
>>>
>>>>No.  We've considered this carefully over the course of several Kepler
>>>>meetings. We also did an experiment with doclets in a previous release
>>>>(which is currently not working because Sun broke their doclet code in
>>>>JDK 1.5), and determined the format is not optimal for our needs.
>>>
>>>
>>>That doclet code was implemented against JDK 1.4 because Sun hadn't
>>>released the Javadoc source code for 1.5 at that point.  I've just
>>>peeked
>>>in the JDK 1.5 source and it looks to be there now.
>>>
>>>>In addition, this is user documentation, not developer documentation,
>>>>and will need to be edited on a different cycle and by different  people
>>>>than the source code.  So we feel it is better to not tie it to
>>>>revisions of the java files.  In addition, we need to be able to
>>>>include
>>>>both natural language documentation and machine-readable documentation
>>>>in the form of OWL-DL statements.  So we decided that it was best to
>>>>group both of these types of documentation within the MoML description
>>>>of an actor.  As a result, the documentation can still be used in many
>>>>contexts as can doclets (ie, context sensitive help and html user
>>>>manuals).
>>>
>>>
>>>There's nothing to prevent your putting both natural language and  OWL-DL
>>>statements in Javadoc comments in Java source files.
>>
>>The main reason for not adding documentation in the Java source is that
>>the people who are writing the documentation won't always be the
>>developers. And we decided that it is not the best place for a
>>non-developer to add documentation.
>>
>>>
>>>Yes, I agree that sometimes it's good to have the separation between
>>>source
>>>code and documentation.  On the flip side, including documentation
>>>directly
>>>in the source helps keep them in sync.  This is why source-level
>>>documentation works in a lot of cases.  Say you define a TypedIOPort in
>>>your actor source, then it's easy to add a Javadoc comment right above  that
>>>to say what it does, and have the doclet automatically generate
>>>documentation based on that to inform the user about this port.
>>
>>I agree. This is a drawback. As a solution, we thought of having
>>template generators or validators for documentation. And the only place
>>we'll have documentation will be the extra file.
>>
>>>>Finally, we need the same documentation for composite actors and
>>>>specialized atomic actors that we do for generic atomic actors, and so
>>>>the java code is not an option here (because composites don't have any
>>>>java code that is relevant to the specialized actor, and specialized
>>>>atomic actors can not be documented in the more generic java code).   As
>>>>a result, we decided it was best to use the MoML document which is
>>>>common to both composite and atomic actors to house the documentation.
>>>
>>>
>>>Doclets being implemented in Java are very flexible.  In our old doclet
>>>implementation, when we were given a Java class to generate
>>>documentation
>>>for, we instantiated the class using Ptolemy, and grabbed information
>>>about
>>>each port automatically, information such as the type of port (string,
>>>int), direction (input, output), etc.
>>>
>>>Since we have the javadoc source, I'd wager it's feasible to have it
>>>automatically find a list of xml/moml files that represent
>>>composite/specialized actors or documentation for them, and either
>>>instantiate them using Ptolemy and grab documentation from it using
>>>Ptolemy, or XML parse it for documentation.  Then that documentation
>>>can be
>>>combined with documentation generated for Java source-based actors to
>>>create an index of actors.
>>
>>That's what we have at the moment. But instead of going through the
>>javadoc as we did before, we're going through the list of registered
>>actors in Kepler. However, the approach is similar. The source code
>>Nandita worked on is in the CVS. Would be great to get your comments on
>>it.
>>-ilkay
>>
>>>
>>>Xiaowen
>>>
>>>_______________________________________________
>>>Kepler-dev mailing list
>>>Kepler-dev at ecoinformatics.org
>>>http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler- dev
>
>--
>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>Matt Jones                                   Ph: 907-789-0496
>jones at nceas.ucsb.edu                    SIP #: 1-747-626-7082
>National Center for Ecological Analysis and Synthesis (NCEAS)
>UC Santa Barbara     http://www.nceas.ucsb.edu/ecoinformatics
>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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