Re: Re: phpdoc and web services

Manuel Lemos wrote:

Also, another point is that *doc markup is a bit cryptic when it comes to the characters that are use to delimit keywords. I think that it would be a better solution to use XML because there plenty of tools parse it and it would more encouraging to extend because it would not require to maintain a special purpose parser.

I have a doc system in the works that uses XML, if you're interested in seeing it. It's a lot more bloated than it needs to be because it parses using XSLT as well as without for people who don't have PHP built w/ it. It doesn't support multiple languages either, but the DTD could easily be extended (I kept it simple so it's easy to remember and work with). Usage is somewhat like PHPdoc, where the documentation is only inside special comment tags /*! xml docs !*/ It's part of a larger project, but it's downloadable at: The link is http://www.simian.ca/downloads/opensource/saf-2.0.tar.gz Look at saf/docs/DocReader/DocReader.html for documentation and saf/lib/DocReader/DocReader.php for the actual class. There's an XSL file I use with it (not sure if it's in the tarball), which is at: http://www.simian.ca/downloads/opensource/to_html.xsl

In MetaL based classes I embedded documentation naturally in the source code of the classes because it is already in XML. The result is wonderful: not only I can embed multilingual documentation but I can embed any sort of tags that will be ignored by the MetaL compiler module for generating classes but it will be handled by the process that generates documentation from the class code. This means that I can extend with whatever markup I want.

This sounds pretty cool. I'm excited for when we actually get to see MetaL and play with it. :)

You may see an example here, actually of a generic SOAP server base class. http://phpclasses.upperdesign.com/browse.html/package/251 Notice how it got all nicely hyperlinked. All that is generated for device indepedent documentation templates that automate documentation exctration.

Admittedly, my docs don't quite match PHPdoc for prettiness, nor yours. Of course, since it's XML, that's a simple XSL change. :) I also wanted to create XSL styles that could translate it into other doc formats, but I'm not sure exactly my intention here, and I'd probably do better to put that off for now.

Actually that gave me a good idea of generating WSDL from the public methods of a class defined in MetaL. It is a very trivial thing implementing in MetaL. Thanks for sharing the idea.

Automatic web services coding in MetaL now... you're a tease! :)

Yes, I think efforts in this field should be merged too because there is no great point in different groups of people in the PHP developer community to propose different standard. Hopefully people agree onto moving to XML based documentation markup to make it more easily extensible.

I tend to agree, although XML docs tend to be much more long-winded than PHPdoc, but I'm not sure if that matters. They're also a little less readable. For instance, if you stick XML docs throughout your code, then you can end up with a case where you're sticking PHP inside HTML (we know better than that, but still), then you're sticking XML inside your PHP, then if you want examples, well, toss in a CDATA section and put some more PHP into it, and it just seems a little recursive and messy. Almost leads to the debate over templating methods (pipeline vs callback). But I like it, and there's a simple solution to that: code highlighting in my editor makes it all good. -- Lux