Gerald Richter wrote:
> 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: [idea 1 snipped] > 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'm in favor of the second proposal with the following amendments: - Don't use perl comments, but normal pod. This way the classes' docs can be still read normally with usual perldoc and used by all pod2foo utils. So when you document a method you go: =head1 @method foo() @param @return @note =cut - Do not use @token, but #token or anything else but tokens starting with @/%/$ since they will confuse readers using the usual pod reading/converting utils. Since we don't use javadoc per se, but only using its concepts, that shouldn't be a problem. ---------------------------------------------------------------------- If we go with this solution, we need to spec out the token lines. So I've started to write the spec for this: - each token line should start with 2 spaces, so you can do: #param .... #param ... and perldoc not wrapping these two as one paragraph. 1 will do as well, 4 is too many, and to be consistent 2 will be nice. Another reason is for determination of the token's end. (see the next item) - a single token can be multilined and include \n\s*\n. The end of the token is determined by either of: o beginning of the next token o text starting from the beginning of the line (which includes the end of pod section tag: =cut) - $token =~ s/[\s\n]$//s so no problem to add new lines between tokens. - the sections inside a token can be separated with any spacing style convenient to its author (spaces, tabs), but try to be consistent and if possible to organise the text in columns to make it easier to maintain. #token name1 type1 comment1 #token name2 type2 comment2 - we need to decide what are the valid tokens, and I would suggest to make them as short as possible to leave more space for the comments to fit in one line. I also like them to be of the same length if possible. This will make the alignment of the next column much easier. I suggest: #name #arg (or parm) #rtrn #dscr #note #side (side effect) the parser should be able to do validation to spot typos and missing must tokens, my be using #tag# will be better than? #name# #arg # #rtrn# #dscr# #note# #side# we also need a short and long description for each method if possible (ala main doc): =head1 NAME This is a short descr =head1 DESCRIPTION This is a long descr. =cut so something like: #abst# (abstract, short decr) #dscr# (long description) and at least one must exist (so if you don't want to write the two, have any of these or we can decide on one that's a must). Alternatively we can always extract the description as anything starting on the next line after the #name# token. - the must tokens should be (for parser validation): #name# #dscr# - the #name# token should include sample usage, with [] used for optional arguments. these argument names are then used in #arg# column: #name# foo ($bar, \@array, [$comment]) This method does foo #arg# $bar some value #arg# \@array a ref to an array #arg# $comment comment... the only thing I'm not sure about is how to handle situations where the same method can be called in many different ways. For example a method which if the first argument is a ref to an array expects the second argument to be a ref to an another array, and if a ref to a hash it expects a ref to an another hash. i.e.: foo(\@bar, \@array) and foo(\%hash, \%another_hash) - probably there are other issue to think of _____________________________________________________________________ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://ticketmaster.com http://apacheweek.com http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
