Hi,
there was recently a thread about documention. The important thing that
comes out for me, was that we need some way to store and retrieve meta data
about classes, methods etc. because Perl itself, can't provide it. This
metadata is necessary at the one side for generating docs about the
interface and on the other side for supporting things like Perl beams that
are able to programmaticaly provide their own API, maybe implementing things
like SOAP (on top of it). It could be also usefull for parameter validation
and I guess more things could be done with it.
My main point at the moment is documentation, because that's something that
starts right now (or has already started). I like to have a standart way how
documentation should be written and if we provide all the necessary
information already in some way for the docs, this information should be
also useable in the future for things like Perl beans.
There were two idea come up on the list until now:
1.) Store these informations in attributes.
Example:
sub MyService::foo
: Parameters (
My::Class var,
[in/out] float FloatNum,
[out] int Something
)
{ "foo"; }
+ easly programmaticaly accessable, because attributes are a part of Perl
(5.6.0+)
+ already used by modules for parameter validation, web services and maybe
more
- not supported in Perl 5.005
- not possible to retrives the meta information, without loading the module
via require, which is not always possible. For example a lot of Apache::*
modules, can not successfully loaded outside of mod_perl
2.) Put the information as comments in a JavaDoc/doxygen like format into to
the module or pods
Example:
#!
# @method MyService::foo
#
# foo implements some very important things
#
# @param [in] My::Class var nice comment about var
# @param [in/out] float float_num comment for float_num
# @param [out] int something more comments
#
# @note Don't called it
#
+ no dependency on Perl version
+ information could be retrieved without loading the code
+ also usable in not Perl code files, like XS code, pod files etc.
- need an extra parser and the meta information must be provided by some
extra facility which "database" must be kept in sync with the source
I personaly would prefer solution 2, because it gives us more flexibility. I
don't see a problem with providing the meta information at runtime for
solution two. By providing a standard module that anybody can plug into his
Makefile.PL, which causes the meta data extracted on every make, will make
sure it's up to date. The Metadata could be either put into an extra module
i.e. for Module P5EE::mymod, we would have a P5EE::Meta::mymod that is
automaticly generated out of the Metadata inside of P5EE::mymod and provides
this information easly for example as a hash or as a set of objects. The
other possibilities is to put the metadata inside a XML file that gets
installed along with the pm file and have a parser that extracts the
metadata when needed.
I would like to get your feedback about this and afterwards to start coding,
so we have soon an standard way for writing docs and a tools for creating
them (into pod, html, pdf, xml...)
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: [EMAIL PROTECTED] Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
