Re: phpdoc and web services

Hello, Lukas Smith wrote: > > Hi, > > I just wanted to point you all to an effort by the phpedit > (ww.phpedit.org) folks. > They are currently building something similar to phpdoc but according to > their author he is trying to get some extra features into their thing. I hope is multilingual documentation support. One of the limitations of phpDoc/JavaDoc/Knuth literate programming is that they only support one documentation language. It seems that a lot of people assume that documentation in English is sufficient for everybody. I know for a fact that it isn't true, especially today that it seems that English is no longer the idiom that most people speak on the Internet. 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. 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. 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. > Also I recently proposed to him to look into wsdl and how that could be > integrated in the documentation generation. This would be very cool and > would help php greatly in future development (I just did a presentation > on sopa, wsdl, uddi and I was blown away by the systinet wasp server and > how easy it was to create a soap based application and have the wsdl > document automatically generated). That is a very good idea. I am not sure if the current PHPdoc supplies all the necessary information to generate WSDL based service descriptions from class methods. Maybe that is why phpedit people are extending it. 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. > The developers of phpedit seemed to like the idea (as can be read on the > phpedit QA mailinglist) > > Even if none of you guys like what phpedit is doing and want to stick > with phpdoc adding wsdl generation would be very cool. This feature > could also have tie-ins with the soap class that someone mentioned is > being developed for pear atm (or the xml-rpc/soap extensions that are > build for php). 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. Regards, Manuel Lemos