[kepler-dev] Generating simple actor documentation using Javadoc

[Ilkay Altintas]

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