[kepler-dev] Generating simple actor documentation using Javadoc

[Bertram Ludaescher]

>>>>> "SAN" == Stephen Andrew Neuendorffer <neuendor at eecs.berkeley.edu> writes:
SAN> 
>> 
>> 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)
SAN> 
SAN> They don't have this type...  

That's good to know. The naive user, when looking at the actor ports
in Vergil would however observe this type when moving the mouse over
the port. When connecting up ports (thus providing additional type
constraints) and hitting "run" (actually we only need prefire I
guess), a more specific type is inferred by the system.

But the type {alpha} -> alpha isn't easily visible to the user

SAN> They should implement the correct type 
SAN> constraints
SAN> for {alpha} -> alpha... I agree it is awkward that such constraints are 
SAN> specified in a
SAN> different way, but they must declare it.  I have long wanted a more 
SAN> declarative way
SAN> of specifying such things: essentially expression language syntax for type 
SAN> constraints.

right!

SAN> Note that quite alot of information is specified operationally in actors,
SAN> rather than declaratively.  

yep -- I guess there might be a need for both (in some apps)

SAN> E.g. type constraints.  Choices added through 
SAN> the addChoice
SAN> mechanism.  Default parameter values.  Reactions to changed attributes.
SAN> Such mechanisms are simple to build in the short term, but really bog down in
SAN> the long term...
SAN> 
>> A user-defined declaration could go a step further (again, say similar
>> to Haskell) and say
>> actorX :: {alpha} -> alpha                         (4)
>> || isNumeric(alpha)
SAN> 
SAN> Yes...  This is one important role of type classes in Haskell. 

yep -- there is a special syntax for it: Num alpha => [alpha] -> alpha

SAN>  Ptolemy
SAN> has a limited form a type classes, in that you can say input <= numeric, to
SAN> guarantee that the actor takes any numeric type, or input <= array{general}
SAN> to guarantee that an actor takes any array type.  The same issues come up in
SAN> object oriented languages when specifying generic, templatized classes.... 
SAN> it's
SAN> essentially equivalent to "This is a class that is a template on type T, 
SAN> where T
SAN> must have a foo method that returns T and a bar method that takes int".
SAN> 
SAN> Going beyond this is I think an important research issue.  Unfortunately, I 
SAN> think
SAN> we've reached the practical limits of the type system as we've formulated 
SAN> it currently.

yeah -- it's very powerful as it is already! And very flexible!

SAN> I think the point is that all of these 'semantic types' should be declared, 
SAN> checked and then
SAN> visible in the javadoc.  This doesn't necessarily mean we need more javadoc 
SAN> tags,
SAN> just that we need to better extract the information that Ptolemy is already 
SAN> using.
SAN> 
SAN> Writing javadoc interpreters is not hard... It could instantiate an actor 
SAN> and then start
SAN> extracting the required information from it.
SAN> 
SAN> Steve