At 09:32 PM 11/27/2001 +0100, Gerald Richter wrote: .... >2.) Put the information as comments in a JavaDoc/doxygen like format into to >the module or pods .... >I personaly would prefer solution 2, because it gives us more flexibility. I ....
Hi, I definitely like Option 2 as well. In order to get the documentation moving quickly for my own proposals, I am homegrowing my own solution, called "perldocs". It has three elements. * Straight POD so that it works right out of the box from Makefile.PL See sample output at: http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue * Conventions for what sections should be in the POD's and how they should be formatted so that a parser can pick up the data. The POD style doc is here: http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/podstyle.html An example using the format is here: http://www.officevision.com/pub/p5ee/software/P5EEx/Blue/P5EE.pm And its output it here: http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/P5EE.html * A javadoc-style frame generator which 1. creates the frames docs, summary docs, and xref docs we are familiar with from javadoc. See some preliminary output can be seen here: http://www.officevision.com/pub/p5ee/software/htdocs/api/ 2. will validate as many of the redundant pieces of information as possible which are coded into the POD doc with each other and with pieces of information which can be parsed from the Perl code itself. This will be highly configurable as to what generates a warning, what generates an error, etc. so that a project can be very strict or not so strict. The generator/validator I have whipped together are called "perldocs" ("perldoc" was already taken). ;-) "perldoc" is in the P5EEx::Blue area, under the "sbin" directory, and it fits well into the Makefile.PL process. See it at: http://cvs.perl.org/cvsweb/p5ee/P5EEx/Blue/sbin/perldocs?rev=HEAD&content-ty pe=text/x-cvsweb-markup I have really not thought too much about using the metadata at runtime, although I have seen on the list that others have discussed it at length. >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 like Gerald's suggestion to store metadata in separate files, generated at make-time. I like the idea of Dumper-style (raw perl) format for runtime efficiency and XML format for flexible document generation. I guess it makes sense for those who are serious about working on the documentation and meta-data-for-bean-like-behavior stuff to declare themselves so that we don't hopelessly duplicate our efforts. Nonetheless, like the rest of P5EEx, there will be plenty of duplication while things are prototyped. Stephen At 09:32 PM 11/27/2001 +0100, Gerald Richter wrote: >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 >------------------------------------------------------------- > > > >
