[kepler-dev] Generating simple actor documentation using Javadoc

[Christopher Brooks]

Looks interesting!

I think that user supplied javadoc tags are supposed to
have a . in the name so as to avoid conflicts.

I seem to remember that I had to use @Pt.ProposedRating
instead of @ProposedRating or else I got warnings under the javadoc
that comes with Java 1.5.   I'm on the road so I can't verify this.

I agree with Edward that with a sufficiently rich javadoc syntax, we
are most of the way to an actor definition language.   I'm not very
happy with how we declare Parameters and then set the types
in the constructor.  It would be better if Parameter types and 
the documentation were more tightly coupled.

I for one would prefer to see javadoc comments near the parameter
definition.  I've found that the greater the distance between the code
and the comment, the less likely the comment is to be updated.


-Christopher


--------

    
    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/d
   o
    clets/Taglet.html
    
    _______________________________________________
    kepler-dev mailing list
    kepler-dev at ecoinformatics.org
    http://www.ecoinformatics.org/mailman/listinfo/kepler-dev
--------