[kepler-dev] Generating simple actor documentation using Javadoc
Edward A Lee
eal at eecs.berkeley.edu
Tue Aug 10 04:22:10 PDT 2004
Ilkay:
Is the focus here on on-line documentation or printed?
I would think we would want to focus on on-line documentation.
If so, then I think this is much more heavyweight than we need...
All the information you need is already available in existing
actor Java files plus an instance of the actor...
I think that adding a whole suite of doclets means a great deal
of rewriting of existing actors and training of actor writers...
I would try to avoid adding any doclets...
If we are going to rewrite actors anyway, I would go further
than this and define a meta-language for an actor-generator.
We had this in Ptolemy Classic. Below is what an actor definition
looked like in Ptolemy Classic. A preprocessor would translate
this into C++ files and html files. In our case, the actor generator
could produce "correct" definitions of the clone() method, for
example, and take care of creating ports and parameters in the
constructor. Today, I would do this not as a preprocessor
but as an Eclipse plug in.
defstar {
name { Abs }
domain { SDF }
desc { Output the absolute value of the input value. }
version { @(#)SDFAbs.pl 1.3 01 Oct 1996 }
author { William Chen }
copyright {
Copyright (c) 1990-1996 The Regents of the University of California.
All rights reserved.
See the file $PTOLEMY/copyright for copyright notice,
limitation of liability, and disclaimer of warranty provisions.
}
location { SDF main library }
htmldoc {
Outputs absolute value of the input.
<a name="absolute value"></a>
}
input {
name { input }
type { float }
}
output {
name { output }
type { float }
}
go {
double t = input%0;
if (t < 0.0) t = -t;
output%0 << t;
}
Edward
At 02:26 AM 8/10/2004 -0700, Ilkay Altintas wrote:
>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
------------
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