[kepler-dev] agenda for kepler meeting
Edward A Lee
eal at eecs.berkeley.edu
Thu Jun 3 07:57:56 PDT 2004
At 10:18 PM 6/2/2004 -0700, Bertram Ludaescher wrote:
>g) documentation standards: e.g., we might have a certain minimal
>template for a "manpage" style documentation of each actor that goes
>in the cvs repository. This can be part of the Java doc, but it should
>be clear how those look like and what is expected. I think overall at
>least the following are needed:
>g1) actor documentation (for users); similar to "man <actor>"; for the
>command line challenged those could come up when one right clicks on
>an actors and asks "get documentation". This is already in place
>thanks to Ptolemy/Vergil but we need some conventions what goes in the
>javadoc for an actor
>g2) workflow documentation: there may be two versions of it "Outreach"
>and "Real User". The former may be include a snapshot with an overview
>and a page or two explaining what the workflow does and how it
>works. The "Real User" documentation views a workflow as "serious
>application" and is thus user manual for that specific workflow... we
>probably won't have those anytime soon!?
On these, I have two comments:
1) Ptolemy Classic had a very nice actor documentation feature
that we could emulate. We would implement it as a Doclet,
so it would use the same source code that is used by Javadoc.
But the documentation that it generates would look very
different. Whereas the Javadoc emphasizes the object-oriented
to an actor, our documentation needs to emphasize its
actor-oriented interface. Something like:
ActorName: First sentence of the class documentation.
- firstParameter: Documentation from javadoc for the public member.
- firstPort: Documentation from javadoc for the public member.
- secondPort: ...
The entire class documentation.
See also: hyperlinks to related actors.
Demos: hyperlinks to demos.
Tests: hyperlinks to tests.
Base class: hyperlink to base class doc (which is Javadoc if there
is no actor doc).
All of this could be done as a doclet... It's just work...
The output would be HTML, or better yet, XML for viewing with
a style sheet (but we have to be sure the HTML renderer in
Java supports the style sheet). When viewed within Ptolemy II,
the hyperlinks would open the relevant models.
2) Rowland Johnson added to version 4.0 a Documentation attribute
that you can drag into a model and double click on to view
the documentation of the model. This could be augmented to
generate the boilerplate for documentation like the actor
documentation above, if the documentation doesn't already
exist. If the documentation does exist, it should parse the
HTML/XML and make it consistent with the model (e.g., the
ports or parameters may have changed).
The current version simply looks for the doc file in a standard
place, and not finding it, presents a file browser. This is not
that useful, but augmenting it as above would be a big help at
relatively modest cost in effort.
These two things are on my to-do list, but my to-do list is pretty
Edward A. Lee, Professor
518 Cory Hall, UC Berkeley, Berkeley, CA 94720
phone: 510-642-0455, fax: 510-642-2739
eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal
More information about the Kepler-dev