> 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.
It does, true, but it doesn't say anything about the nature of those
parameters, what they are meant for or whether they are expected to be
strings, integers or object references.
> 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).
Note that ModInfo does not use POD, although it can generate it if so
desired. It uses XML files external to the perl script stored alongside
them: i.e., MyModule.pm is accompanied by MyModule.xml. The Perl comments
being discussed are merely used to create the XML files, and provide a way to
keep the source of the information near the code. The comments are only used
when the developer updates the XML files. You'll note that this neatly
sidesteps the evaluation problem that Attributes::* has, since running the
module is not necessary for getting at the metadata.
> 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?
My whole problem with all the modules I've seen so far that try to provide
introspection capabilities is that they incur runtime overhead when the
developer may not really want it. I designed ModInfo to only create overhead
when the user of the module wants the information. When he wants the
information, he instantiates ModInfo, asks for the data on the module he's
interested in, and at that time the XML is parsed, otherwise there is no
overhead at all.
I haven't looked at the Attribute::* modules yet, so they may follow this
same philosophy, but if you find yourself having to "use Attribute::*;" in
your module in order to take advantage of it, then it falls into the runtime
trap.
With all this in mind, if a marriage between ModInfo and Attributes::* (or
any other runtime metadata system) was desired, I think the best thing to do
would be to work up a utility that evalutes a module that implements
Attributes::* and then generates the XML file that ModInfo looks for. Note
that this would only need to be done whenever the module was modified. Then
you could have your cake and eat it, too.
I'd also like to mention that the comments used by ModInfo don't have to be
included in the module itself. I've heard some comments in the recent past
about extensive commenting causing compile-time slowdowns in Perl. The
ModInfo directives can be off-loaded to an external file that also sits
alongside the module without any problem.
jpt
-------------------------------------------------------
