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

[Matt Jones]

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