[kepler-dev] agenda for kepler meeting

[Bertram Ludaescher]

Edward:

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


Bertram


>>>>> "EAL" == Edward A Lee <eal at eecs.berkeley.edu> writes:
EAL> 
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> 
EAL> On these, I have two comments:
EAL> 
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> 
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> 
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> 
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> 
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> 
EAL> These two things are on my to-do list, but my to-do list is pretty
EAL> big still...
EAL> 
EAL> Edward
EAL> 
EAL> 
EAL> 
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