[kepler-dev] Generating simple actor documentation using Javadoc
Bertram Ludaescher
ludaesch at sdsc.edu
Tue Aug 10 15:25:59 PDT 2004
>>>>> "EAL" == Edward A Lee <eal at eecs.berkeley.edu> writes:
EAL>
EAL> I think the bigger risk here is not that people won't provide
EAL> the documentation ("the tags are optional"), but that the
EAL> documentation will be wrong. Why require doc tags for information
EAL> that can be inferred from the Java code (either by executing the
EAL> code to create an instance of the actor or by parsing it, using
EAL> Eclipse for example)?
That's very true. If we can infer certain information and put it in
the "right place" (TBD ;-) then by all means we should do it.
EAL> The general principle followed in Ptolemy
EAL> Classic was that no piece of information is given twice.
A good principle, in particular when the information is from and for
the machine. Of course texts that are for human consumption need
redundancy (sometimes you have to explain a thing in various ways, to
make sure the message is understood). But this doesn't invalidate your
point: what can be automatically generated shouldn't be declared --
unless it is for consistency checking of course.
For example, I often write a type signature in Haskell although the
system often can infer it from the function definition. But then
again, I can compare these two definitions to see whether they indeed
are consistent (actually the system does that for me)
EAL> Ptolemy II,
EAL> unfortunately, does not adhere to this (e.g., parameter names are
EAL> given several times in a source file). Let's not make it worse, though...
agreed
EAL> I think all the information we need to generate good documentation
EAL> for actors is already there: whether a port is an input or output,
EAL> what it's declared type is, what the type constraints are, etc.
that's very good news. Could we thus insert this information
automatically into the javadoc, maybe as part of a "ant makejavadoc"
or whatever!?
EAL> If we create another, separate syntax for specifying the same thing,
EAL> the information is very likely to be wrong or missing much of the time...
Indeed we might not need a separate syntax. Just a human readable form
(XML is not that friendly for the human eye, but a convenience for
application programmers) that is generated by the system and injected
in the right places of the documentation
EAL> I would suggest instead a doclet that creates an XML representation of
EAL> existing Javadoc tags, e.g. (using MoML as the schema):
EAL>
EAL> <entity name="actorName" class="ptolemy.doclet.ActorDocumentation">
EAL> <configure>
EAL> ... class comment goes here ...
EAL> </configure>
EAL> <property name="foo" class="ptolemy.doclet.PublicMember">
EAL> <configure>
EAL> ... Javadoc comment for the public member named foo ...
EAL> </configure>
EAL> </property>
EAL> </actor>
EAL>
EAL> It would then be a rather simple matter to create a tool that,
EAL> given an instance of the actor and a pointer to the XML file above,
EAL> produced very good documentation for the actor.
sounds good to me too.
btw: in terms of inferred vs. declared, there is one point though, now
that I think about it:
A noticed that several PT actors have a type e.g., of the form
actorX :: {unknown} -> unknown (1)
while really the type is
actorX :: {alpha} -> alpha (2)
(as opposed to say {alpha} -> beta) (3)
I guess that information is embedded in the constraint and/or Java
code. But it is worthwhile putting it in the signature, since (2) and
(3) say more than (1).
A user-defined declaration could go a step further (again, say similar
to Haskell) and say
actorX :: {alpha} -> alpha (4)
|| isNumeric(alpha)
to express the additional constraint that the can accept an array of
type alpha as long as alpha is a Numeric type. More general constraint
expressions can be built. Best of all, this provides for the semantic
type folks among us a mechanism to also state semantic constraints.
(Oversimplifying, we could have sth like
isNumeric(alpha) /\ hasUnitType('mass') /\ hasUnit('kg')
/\ isInstanceOf('person_weight') ... or whatever
OK, we're mixing some short term needs with some research issues
here... but I thought I provide this as an addtl. context...
cheers
Bertram
EAL>
EAL> Edward
EAL>
EAL> At 08:36 AM 8/10/2004 -0700, Bertram Ludaescher wrote:
EAL>
>> 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
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
More information about the Kepler-dev
mailing list