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

[Ilkay Altintas]

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