[kepler-dev] agenda for kepler meeting

[Bertram Ludaescher]

Matt:

Thanks for the follow up. 

FYI: several of us (Shawn, Ilkay, myself) will be gone to various
conferences (SSDBM, SIGMOD/PODS, ISC) large chunks of this month.

Bertram

>>>>> "MJ" == Matt Jones <jones at nceas.ucsb.edu> writes:
MJ> 
MJ> I agree, these are nice suggestions for documentation.  In addition, I 
MJ> think we can go further.  The process of documenting actors and 
MJ> workflows is tightly tied to the process of doing semantic registration 
MJ> as we've discussed with you and Shawn.  We talked a bit about semantic 
MJ> registration during this kepler meeting in SB over the last two days, 
MJ> and have some kepler-specific tasks to follow up on with you and Shawn. 
MJ>   If we have both natural language documentation and formal semantic 
MJ> registrations as documentation, it would be nice if they could be stored 
MJ> together.  Chad has the task of following through on designing, with 
MJ> KR/SMS folks, a precise solution to storing the registration mappings 
MJ> for actors, workflows (MoML), web services (WSDL), and data (EML).  This 
MJ> is a necessary precursor to our ability to implement the ontology-driven 
MJ> browsing features that we discussed (also a major topic of our meeting).
MJ> 
MJ> Cheers,
MJ> Matt
MJ> 
MJ> Bertram Ludaescher wrote:
MJ> 
>> 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
MJ> 
MJ>