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

[xiaowen]

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.

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.

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

Xiaowen