[kepler-dev] agenda for kepler meeting

[Edward A Lee]

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.
    Parameters:
      - firstParameter: Documentation from javadoc for the public member.
      - ...
    Input ports:
      - firstPort: Documentation from javadoc for the public member.
    Output ports:
      - secondPort: ...
    Details:
      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
big still...

Edward



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