[kepler-dev] Generating simple actor documentation using Javadoc

[Stephen Andrew Neuendorffer]

>
>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)

They don't have this type...  They should implement the correct type 
constraints
for {alpha} -> alpha... I agree it is awkward that such constraints are 
specified in a
different way, but they must declare it.  I have long wanted a more 
declarative way
of specifying such things: essentially expression language syntax for type 
constraints.
Note that quite alot of information is specified operationally in actors,
rather than declaratively.  E.g. type constraints.  Choices added through 
the addChoice
mechanism.  Default parameter values.  Reactions to changed attributes.
Such mechanisms are simple to build in the short term, but really bog down in
the long term...

>A user-defined declaration could go a step further (again, say similar
>to Haskell) and say
>         actorX :: {alpha} -> alpha                         (4)
>                || isNumeric(alpha)

Yes...  This is one important role of type classes in Haskell.  Ptolemy
has a limited form a type classes, in that you can say input <= numeric, to
guarantee that the actor takes any numeric type, or input <= array{general}
to guarantee that an actor takes any array type.  The same issues come up in
object oriented languages when specifying generic, templatized classes.... 
it's
essentially equivalent to "This is a class that is a template on type T, 
where T
must have a foo method that returns T and a bar method that takes int".

Going beyond this is I think an important research issue.  Unfortunately, I 
think
we've reached the practical limits of the type system as we've formulated 
it currently.
I think the point is that all of these 'semantic types' should be declared, 
checked and then
visible in the javadoc.  This doesn't necessarily mean we need more javadoc 
tags,
just that we need to better extract the information that Ptolemy is already 
using.

Writing javadoc interpreters is not hard... It could instantiate an actor 
and then start
extracting the required information from it.

Steve