[kepler-dev] agenda for kepler meeting

Bertram Ludaescher ludaesch at sdsc.edu
Thu Jun 3 09:07:45 PDT 2004


These are great suggestions! Let's see what the few and the brave
getting together over the next two days come up with.

But your suggested system sounds very cool..


>>>>> "EAL" == Edward A Lee <eal at eecs.berkeley.edu> writes:
EAL> 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!?
EAL> On these, I have two comments:
EAL> 1) Ptolemy Classic had a very nice actor documentation feature
EAL>     that we could emulate.  We would implement it as a Doclet,
EAL>     so it would use the same source code that is used by Javadoc.
EAL>     But the documentation that it generates would look very
EAL>     different.  Whereas the Javadoc emphasizes the object-oriented
EAL>     to an actor, our documentation needs to emphasize its
EAL>     actor-oriented interface.  Something like:
EAL>     ActorName: First sentence of the class documentation.
EAL>     Parameters:
EAL>       - firstParameter: Documentation from javadoc for the public member.
EAL>       - ...
EAL>     Input ports:
EAL>       - firstPort: Documentation from javadoc for the public member.
EAL>     Output ports:
EAL>       - secondPort: ...
EAL>     Details:
EAL>       The entire class documentation.
EAL>     See also: hyperlinks to related actors.
EAL>     Demos: hyperlinks to demos.
EAL>     Tests: hyperlinks to tests.
EAL>     Base class: hyperlink to base class doc (which is Javadoc if there
EAL>       is no actor doc).
EAL>     All of this could be done as a doclet... It's just work...
EAL>     The output would be HTML, or better yet, XML for viewing with
EAL>     a style sheet (but we have to be sure the HTML renderer in
EAL>     Java supports the style sheet). When viewed within Ptolemy II,
EAL>     the hyperlinks would open the relevant models.
EAL> 2) Rowland Johnson added to version 4.0 a Documentation attribute
EAL>     that you can drag into a model and double click on to view
EAL>     the documentation of the model.  This could be augmented to
EAL>     generate the boilerplate for documentation like the actor
EAL>     documentation above, if the documentation doesn't already
EAL>     exist.  If the documentation does exist, it should parse the
EAL>     HTML/XML and make it consistent with the model (e.g., the
EAL>     ports or parameters may have changed).
EAL>     The current version simply looks for the doc file in a standard
EAL>     place, and not finding it, presents a file browser.  This is not
EAL>     that useful, but augmenting it as above would be a big help at
EAL>     relatively modest cost in effort.
EAL> These two things are on my to-do list, but my to-do list is pretty
EAL> big still...
EAL> Edward
EAL> ------------
EAL> Edward A. Lee, Professor
EAL> 518 Cory Hall, UC Berkeley, Berkeley, CA 94720
EAL> phone: 510-642-0455, fax: 510-642-2739
EAL> eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal

More information about the Kepler-dev mailing list