[kepler-dev] Generating simple actor documentation using Javadoc
Edward A Lee
eal at eecs.berkeley.edu
Tue Aug 10 10:57:16 PDT 2004
I think the bigger risk here is not that people won't provide
the documentation ("the tags are optional"), but that the
documentation will be wrong. Why require doc tags for information
that can be inferred from the Java code (either by executing the
code to create an instance of the actor or by parsing it, using
Eclipse for example)? The general principle followed in Ptolemy
Classic was that no piece of information is given twice. Ptolemy II,
unfortunately, does not adhere to this (e.g., parameter names are
given several times in a source file). Let's not make it worse, though...
I think all the information we need to generate good documentation
for actors is already there: whether a port is an input or output,
what it's declared type is, what the type constraints are, etc.
If we create another, separate syntax for specifying the same thing,
the information is very likely to be wrong or missing much of the time...
I would suggest instead a doclet that creates an XML representation of
existing Javadoc tags, e.g. (using MoML as the schema):
<entity name="actorName" class="ptolemy.doclet.ActorDocumentation">
<configure>
... class comment goes here ...
</configure>
<property name="foo" class="ptolemy.doclet.PublicMember">
<configure>
... Javadoc comment for the public member named foo ...
</configure>
</property>
</actor>
It would then be a rather simple matter to create a tool that,
given an instance of the actor and a pointer to the XML file above,
produced very good documentation for the actor.
Edward
At 08:36 AM 8/10/2004 -0700, Bertram Ludaescher wrote:
>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
------------
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
More information about the Kepler-dev
mailing list