> > ok, so what you are going to do with other documentation parts which > aren't exactly API. e.g. DESCRIPTION and extra information for the > methods, like examples of usage? >
Either put them as pod in an extra file or at the end of the module. The parser will assemble the the docs from different places and sources and create one pod document (or maybe some XML which can be used as source for creating pod/html/pdf or whatever) > also where are you going to stick the docs if parts of the project are > autogenerated? (I don't think p5ee must be XS free) > As Matt already said comments can be embedded into the XS files. The autogerneration stuff for mod_perl can do this for the automaticly generated docs from the Apache headers and as above there is the possiblity to have addtional doc sources which the parser will merge. I will make sure that this works. > > > > and we need to add a special comment blocks starts with #! > > > no need to, if your example is followed and the first two columns > matching /^#\s/ can be stripped. > Not sure if it would better to have an extra marker which starts these special comment and the parser would leave all other comments alone. > > you mean you plan to use doxygen as is? No, I just want to borrow the syntax, so people have the same keywords when browseing the Apache header files and the mod_perl sources and any other P5EE docs. > Variable tag length makes it a > an extra effort to align the source docs, and many people won't do this, > you will end up with a little mess :) > On the one side you are right, things should be as easy as possible, on the other side I think it isn't to much work for a programmer to hit the TAB key to get a proper alignment. Haveing variable length keywords is more verbose and therefore easier > > #tag# doesn't looks nice when reading the source. I don't think it > has any > > advantages over #tag > > > maybe, but did you think about docs validation? Yes, of course we should have as much validation as possible, but I don't think it makes any difference for validation if the tag is named #name or #name# > any other ideas? Once > you've hundreds of classes and methods, you will really want the parser > telling you: hey this tag is unknown or that tag is missed. > Yes, of course this is absolutely necessary > > > > #! > > #name foo > > #param \@bar comment > > #param \@array comment > > # > > #name foo > > #param \%hash comment > > #param \%another_hash comment > > # > > that's cool, just make sure that it's a part of the spec and supported > by the parser. > > but on the other hand: > foo($a, [$b [$c]]) > > is much more concise, I'd rather do: > > #name foo($a, [$b [$c]]) > #name foo(\%d, [$b [$c]]) > > and then explain each param once!, otherwise you will end up repeating > params' descriptions and once duplication in place, things will go out > of sync. > That's right duplication isn't good and we should avoid it. 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 -------------------------------------------------------------
