Hi, Gerald!
--- Gerald Richter <[EMAIL PROTECTED]> wrote:
> Do have considered to use JavaDoc like comments. This would allow
> to have
> the same way of comments in C (using doxygen) and Perl (and Java) .
>
> Example:
> #*
> # @method TRACE Tracing function for logging diagnostic messages
> # @param msg STRING Message to send to trace
> # @param trace_lvl STRING Level of tracing required to log msg
>
> Instead of # MODINFO, we start a special comment with #* and
> keywords are
> beginning with @. The "modinfo comment" ends as soon as there is a
> non
> comment line.
>
> What do you think ?
My concern is that this information is presented in script in a
several different ways. First, we have
my($msq, $trace_lvl) = @_;
that already bears *some* information/assumptions about parameters.
Than we *may* have additional meta information for rpc, webservices
or just for types checking. There are Attribute::Webservices (Matt
Sergeant) and Attribute::Signature (James Duncan) that defines such
meta information about parameters. PerlEx (ActiveState) stores
similar information in POD also. I'm working on extending
Attribute::Webservices to provide metainformation for SOAP/XMLRPC
services. I would rather do NOT have third place to define it, yet it
might be not possible to recover this information from Attribute::*
modules without evaluation. Disadvantage of POD is that this
information is not available for dynamic querying and discovery and
you need to make it available to script in some way (thus duplicate).
What probably could be done with Attribute::* modules is to store
this information as attributes and have
# @method something
definition or similar that asks for details on method something().
Package is evaluated (eval { require .... }, only the first time) and
Attribute module is queried to get signature and all meta information
about this particular method. This information is inserted in
generated docs according to specified template. It may not work in
all cases, but it's more flexible and you need to update all your
metainformation in one place, which is your code, so it can't be
outdated. This information is also readable, so there is no confusion
in what means what. Caveat: perl 5.6 required. Thoughts?
Best wishes, Paul.
__________________________________________________
Do You Yahoo!?
Find the one for you at Yahoo! Personals
http://personals.yahoo.com
