[kepler-dev] Generating simple actor documentation using Javadoc
Bertram Ludaescher
ludaesch at sdsc.edu
Tue Aug 10 08:36:54 PDT 2004
All:
I think this is a useful discussion.
The starting point for what has now become a suggestion for new
doclets was that we wanted to provide the user with some additional
"semistructured" documentation. For example, following the
actor-oriented paradigm, users of the system can think of actors as
components with parameters, input ports, and output ports. Thus, it
would be useful to explain this high-level signature along with the
high-level description of what the actor does.
We argued a while back and forth whether end-user oriented
documentation should go along with the code and with the "normal"
documentation of the Java code. We came to the conclusion that it
would probably be a good idea to provide the user documentation right
away and "in place" when the code is written.
Whether the level of detail of all the new document tags is
appropriate or whether a coarser version would be enough, is up for
discussion. Overall the tags are a guide also to the developer to help
explain what an actor does in terms of the ports and parameters it
provides.
I think the doclet approach for now serves the immediate need to
provide some addtl. documentation for the end user in a central place.
I assume that doclets are optional by nature, so we don't have to
provide all of this info until the format has been proven useful.
Your suggestion of actor generator languages is very interesting!
Although different in aim and scope, it reminds me of another
discussion we had here recently on the possibility of devising a
"Kepler/Script" language (or "Ptolemy/Script" for that matter), i.e.,
a scripting-style language for workflow/model for friends of the
textual paradigm. The idea would be that this language is concise to
write for the workflow designer (so it can't be XML), and that from
this the MOML file would be generated.
I'm not sure how this language would look like exactly, but it should
provide a simple means to express the "network topology" of a Ptolemy
model/Kepler workflow. It might also have signature definitions for
actors. Specifically actors that are not implemented yet but used in
the design of a workflow would need such signature definitions.
Something similar to Haskell signature might be used as a starting
point.
For example,
actor foobar(PARAMS) :: INPUTS --> OUTPUTS
|| CONSTRAINTS
where the actor named foobar has parameters, input and output
ports. The constraints further describe type information on the inputs
and outputs (maybe even firing rules etc.... whatever is needed)
Bertram
>>>>> "EAL" == Edward A Lee <eal at eecs.berkeley.edu> writes:
EAL>
EAL> Ilkay:
EAL>
EAL> Is the focus here on on-line documentation or printed?
EAL> I would think we would want to focus on on-line documentation.
EAL> If so, then I think this is much more heavyweight than we need...
EAL> All the information you need is already available in existing
EAL> actor Java files plus an instance of the actor...
EAL>
EAL> I think that adding a whole suite of doclets means a great deal
EAL> of rewriting of existing actors and training of actor writers...
EAL> I would try to avoid adding any doclets...
EAL>
EAL> If we are going to rewrite actors anyway, I would go further
EAL> than this and define a meta-language for an actor-generator.
EAL> We had this in Ptolemy Classic. Below is what an actor definition
EAL> looked like in Ptolemy Classic. A preprocessor would translate
EAL> this into C++ files and html files. In our case, the actor generator
EAL> could produce "correct" definitions of the clone() method, for
EAL> example, and take care of creating ports and parameters in the
EAL> constructor. Today, I would do this not as a preprocessor
EAL> but as an Eclipse plug in.
EAL>
EAL> defstar {
EAL> name { Abs }
EAL> domain { SDF }
EAL> desc { Output the absolute value of the input value. }
EAL> version { @(#)SDFAbs.pl 1.3 01 Oct 1996 }
EAL> author { William Chen }
EAL> copyright {
EAL> Copyright (c) 1990-1996 The Regents of the University of California.
EAL> All rights reserved.
EAL> See the file $PTOLEMY/copyright for copyright notice,
EAL> limitation of liability, and disclaimer of warranty provisions.
EAL> }
EAL> location { SDF main library }
EAL> htmldoc {
EAL> Outputs absolute value of the input.
EAL> <a name="absolute value"></a>
EAL> }
EAL> input {
EAL> name { input }
EAL> type { float }
EAL> }
EAL> output {
EAL> name { output }
EAL> type { float }
EAL> }
EAL> go {
EAL> double t = input%0;
EAL> if (t < 0.0) t = -t;
EAL> output%0 << t;
EAL> }
EAL>
EAL>
EAL>
EAL> Edward
EAL>
EAL>
EAL> At 02:26 AM 8/10/2004 -0700, Ilkay Altintas wrote:
EAL>
>> Hi,
>>
>> Xiaowen and I have discussed on the man-page style user documentation
>> issue and thought of using Javadoc for generating these documents.
>>
>> Below is the short summary of what we have discussed. We're still
>> trying to design this so your comments are appreciated.
>>
>> Thanks,
>> Ilkay
>>
>>
>> Javadoc-based document description
>> ----------------------------------
>>
>> Extending the javadoc by using special tags and a
>> specific doclet has been considered as a method of
>> automatically generating man pages for the user.
>>
>> For these, we are planning to add the following tags
>> to the javadoc and implement taglet for each of them
>> to generate the documentation for it. We will also
>> extend the doclet that generates the documents to use
>> these taglets.
>>
>>
>> @actor {@name}, {@shortdesc}
>> @inputport {@name}, {@dataype}, {@portstyle}, {@shortdesc}, {@exampleValue}
>> @outputport {@name}, {@dataype}, {@portstyle}, {@shortdesc}
>> @inoutport {@name}, {@dataype}, {@portstyle}, {@shortdesc}, {@exampleValue}
>> - @name is the name of the port
>> - @datatype is the type of the port (i.e. integer, string, etc)
>> - @portstyle tells whether this is a multiport
>> - @shortdesc describes what the port does
>> - @exampleValue shows a possible value for the input ports
>>
>> @parameter {@name}, {@paramStyle}, {@type}, {@possibleVaues},
>> {@initialValue}, {@shortDesc}
>> - @name is the name of the parameter
>> - @datatype is the type of the parameter (i.e. integer, string, etc)
>> - @paramStyle tells whether this is a FileParameter, StringParameter,
>> etc...
>> - @possibleValues explains the constraints on the value of this parameter
>> - @initialValue shows a default or example value
>> - @shortdesc describes what the parameter is for
>>
>>
>> All tags names will be in Java convention to be consistent with the
>> Standard doclet.
>>
>> We also want add a couple of extra tags on an actor-level basis. The
>> initial thoughts on what these tags will be are listed below:
>>
>> - We want to have a category tag for each actor and use it for
>> category-based search from the actor tree. The details of this will
>> be discussed later.
>> - We might want a tag to say whether we're documenting a composite
>> actor or not. (By adding a @composite tag.) One way to do that is to
>> put it in a .java file without the actual implementation. We're not
>> sure but we can also give Javadoc two sets of input files on the
>> command line.
>> - We might want a tag to say what domain the actor works in ... PN,
>> or SDF or all, or what.
>> - For actors with variable ports, we'll need a special mechanism.
>>
>> We decided to start our implementation for the actor documentation
>> by the port and parameter additions discussed above. Then well design
>> the more complex additions. To help with the discussion, we'll use the
>> CommandLine actor with the extra tags below as this actor has various
>> kinds of ports and parameters.
>>
>> USE_CASE: CommandLine actor
>>
>> For Javadoc, we'll use the CommandLine actor as an example and create
>> the documentation for it.
>>
>> @actor {@name CommandLine}
>> {@shortDesc
>> Given a command string, the CommandLine actor executes it using the
>> java Runtime class.
>> SUPPORTED COMMAND TYPES:
>> command, command < infile > outfile, command > outfile, command < infile,
>> command [arg1..argn] > outfile, command [arg1..argn]
>> WILL BE SUPPORTED:
>> command [arg1..argn] < infile > outfile, command1 | command 2 }
>>
>> @author Ilkay Altintas
>> @version $Id: CommandLine.java,v 1.20 2004/07/30 21:14:11 altintas Exp $
>>
>> @parameter {@name command},
>> {@paramStyle StringAttribute},
>> {@possibleValues All Unix and DOS commands.}
>> {@initialValue null},
>> {@shortDesc The command to execute.}
>>
>> @outputPort {@name outputFile},
>> {@dataype string},
>> {@portstyle single},
>> {@shortdesc A string that forwards the outputFile parameter if
>> it exists.}
>>
>>
>> @inputPort {@name arguments},
>> {@dataType general},
>> {portStyle multi},
>> {@shortDesc The arguments to the command. Implemented as a multi/
>> input port to support more than one argument. It
>> concatanates the inputs in all the channels. If
>> there
>> is an input file, this port can be empty. }
>>
>> ...I'll extend these examples to cover all the ports and parameters of this
>> actor...
>>
>>
>> References:
>> [1] http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
>> [2]
>> http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/com/sun/tools/do
>> clets/Taglet.html
>>
>> _______________________________________________
>> kepler-dev mailing list
>> kepler-dev at ecoinformatics.org
>> http://www.ecoinformatics.org/mailman/listinfo/kepler-dev
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
EAL>
EAL> _______________________________________________
EAL> kepler-dev mailing list
EAL> kepler-dev at ecoinformatics.org
EAL> http://www.ecoinformatics.org/mailman/listinfo/kepler-dev
More information about the Kepler-dev
mailing list