Re: Re: phpdoc and web services

Hello, Lux wrote: > > 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. This is nice. BTW, if all goes well, maybe soon I can dedicate full time developing the PHP Classes site, so I will add features that were in the todo list, like bulk uploading so you can upload your classes now all at once. > 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 This is very similar to MetaL Class documentation template (see at the bottom of the message). I don't quite like XSL because it is very limited when it comes to the flexibility of the role of the tags. When you want to do something less obvious, you have to go through hops and bounces just to make it happen as a transformation. > > > > 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. :) Well, I am a little behind my schedule because I planned to make a final first public release early next month with bindings for Java and Perl already in place besides PHP. Java bindings are pretty much ready. This means that I can generate Java code from a MetaL class that works seeminglessly to the PHP code that can be generated from the same MetaL class. I was supposed to be working on Perl bindings now, but since there is this opportunity to sell PHP Classes ad space to an real ad network I want to give that the priority because that will allow me to work on it on full time (I don't need to get another job). Anyway, the plan is to develop the Perl bindings and then make the first public release. That may happen in March. Meanwhile MetaL development is closed to a group of developers that are (were supposed to be) evaluating the language usability in order to provide some feedback before the it is released to the public. If you or anybody think you have time to evaluate the language and provide feedback, just mail me privately and I can grant access to the MetaL materials. > > 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. I can do that in MetaL but always from the same template document. The filters will translate device independent document stream in target format representation. > > 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! :) Actually that was the idea forwarded by Lukas. I don't have much use for that right away, but implementing that in MetaL would not take much from now. > > 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. Yes, I think that making it more extensible would be more important. XML would let you use custom tags that only the document renderer would understand and that would not affect the actual class code. Anyway, to make it really extensible I would suggest that you switch to SML (Simplified markup language) which is basically XML with no tag attributes or character entities. Tag attributes cripple extensibility because you can't use tags inside tag attributes. Also tag attributes make it less readable. Regards, Manuel Lemos <?xml version="1.0"?> <!-- @(#) $Header: /home/mlemos/cvsroot/metal/documentation/class-en.documentation,v 1.17 2001/12/14 07:47:50 mlemos Exp $ --> <document> <title>Class: <getclassproperty>title</getclassproperty></title> <author><getclassproperty>author</getclassproperty></author> <authoraddress><getclassproperty>authoraddress</getclassproperty></authoraddress> <body> <list> <p><b>Version:</b> <tt><getclassproperty>version</getclassproperty></tt></p> <heading><link> <data>Contents</data> <anchor>table_of_contents</anchor> </link></heading> <tableofcontents /> <p><link> <data>Top of the table of contents</data> <name>table_of_contents</name> </link></p> </list> <sectionbreak /> <list> <heading><li><mark>Summary</mark></li></heading> <list> <heading><mark>Name</mark></heading> <p><getclassproperty>title</getclassproperty></p> <heading><mark>Author</mark></heading> <p><getclassproperty>author</getclassproperty> (<link> <data><getclassproperty>authoraddress</getclassproperty></data> <url>mailto:<getclassproperty>authoraddress</getclassproperty></url> </link>)</p> <conditionalvalue> <istrue><definedclassproperty>copyright</definedclassproperty></istrue> <then><heading><mark>Copyright</mark></heading><p><getclassproperty>copyright</getclassproperty></p></then> </conditionalvalue> <heading><mark>Version</mark></heading> <p><getclassproperty>version</getclassproperty></p> <conditionalvalue> <istrue><getclassproperty>subclass</getclassproperty></istrue> <then><heading><mark>Parent classes</mark></heading><list><forallparentclasses><p><li><getsubclassproperty>title</getsubclassproperty><conditionalvalue><istrue><getsubclassproperty>abstract</getsubclassproperty></istrue><then> (abstract)</then></conditionalvalue></li></p><p><b>Version:</b> <tt><getsubclassproperty>version</getsubclassproperty></tt></p></forallparentclasses></list></then> </conditionalvalue> <heading><mark>Purpose</mark></heading> <p><getclassdocumentation>purpose</getclassdocumentation></p> <heading><mark>Usage</mark></heading> <p><getclassdocumentation>usage</getclassdocumentation></p> <conditionalvalue> <istrue><definedclassdocumentation>example</definedclassdocumentation></istrue> <then><heading><mark>Example</mark></heading><p><getclassdocumentation>example</getclassdocumentation></p></then> </conditionalvalue> <p><link> <data>Table of contents</data> <name>table_of_contents</name> </link></p> </list> </list> <sectionbreak /> <list> <heading><li><link> <data></data> <anchor>variables</anchor> </link><mark>Variables</mark></li></heading> <list> <forallpublicvariables><li><variablelink><variablename /></variablelink></li><br /></forallpublicvariables> <p><link> <data>Table of contents</data> <name>table_of_contents</name> </link></p> <forallpublicvariables> <heading><link> <data></data> <anchor><variableanchor> <arguments> <variable><variablename /></variable> </arguments> </variableanchor></anchor> </link><li><mark><variablename /></mark></li></heading> <heading>Type</heading> <p><tt><i><variabletypename /></i></tt></p> <conditionalvalue> <istrue><definedvariabledefaultvalue /></istrue> <then><heading>Default value</heading><p><tt><variableconvertedvalue /></tt></p></then> </conditionalvalue> <heading>Purpose</heading> <p><conditionalvalue> <istrue><definedclassdocumentation>purpose</definedclassdocumentation></istrue> <then><getclassdocumentation>purpose</getclassdocumentation></then> <else>Not yet documented.</else> </conditionalvalue></p> <conditionalvalue> <istrue><definedclassdocumentation>usage</definedclassdocumentation></istrue> <then><heading>Usage</heading><p><getclassdocumentation>usage</getclassdocumentation></p></then> </conditionalvalue> <p><link> <data>Variables</data> <name>variables</name> </link></p> </forallpublicvariables> <p><link> <data>Table of contents</data> <name>table_of_contents</name> </link></p> </list> </list> <sectionbreak /> <list> <heading><li><link> <data></data> <anchor>functions</anchor> </link><mark>Functions</mark></li></heading> <list> <forallpublicfunctions><li><functionlink><functionname /></functionlink></li><br /></forallpublicfunctions> <p><link> <data>Table of contents</data> <name>table_of_contents</name> </link></p> <forallpublicfunctions> <heading><link> <data></data> <anchor><functionanchor> <arguments> <function><functionname /></function> </arguments> </functionanchor></anchor> </link><li><mark><functionname /></mark></li></heading> <heading>Synopsis</heading> <p><tt><i><functiontypename /></i> <functionname />(</tt><conditionalvalue> <istrue><functionhasarguments /></istrue> <then><list> <forallarguments><tt><conditionalvalue> <istrue><inoutargument /></istrue> <then>(input and output) </then> <else><conditionalvalue> <istrue><outargument /></istrue> <then>(output) </then> </conditionalvalue></else> </conditionalvalue><i><argumenttypename /></i> </tt><argumentlink> <function><functionname /></function> <argument><argumentname /></argument> </argumentlink><tt><conditionalvalue> <isfalse><lastargument /></isfalse> <then>,<br /></then> </conditionalvalue></tt></forallarguments> </list></then> </conditionalvalue><tt>)</tt></p> <heading>Purpose</heading> <p><conditionalvalue> <istrue><definedclassdocumentation>purpose</definedclassdocumentation></istrue> <then><getclassdocumentation>purpose</getclassdocumentation></then> <else>Not yet documented.</else> </conditionalvalue></p> <conditionalvalue> <istrue><definedclassdocumentation>usage</definedclassdocumentation></istrue> <then><heading>Usage</heading><p><getclassdocumentation>usage</getclassdocumentation></p></then> </conditionalvalue> <conditionalvalue> <istrue><functionhasarguments /></istrue> <then><heading>Arguments</heading><list> <forallarguments><p><tt><b><link> <data><argumentname /></data> <anchor><argumentanchor> <arguments> <function><functionname /></function> <argument><argumentname /></argument> </arguments> </argumentanchor></anchor> </link></b></tt> - <conditionalvalue> <istrue><definedclassdocumentation>purpose</definedclassdocumentation></istrue> <then><getclassdocumentation>purpose</getclassdocumentation></then> <else>Not yet documented.</else> </conditionalvalue></p></forallarguments> </list></then> </conditionalvalue> <conditionalvalue> <isfalse><functionistype>VOID</functionistype></isfalse> <then><heading>Return value</heading><p><conditionalvalue> <istrue><definedclassdocumentation>returnvalue</definedclassdocumentation></istrue> <then><getclassdocumentation>returnvalue</getclassdocumentation></then> <else>Not yet documented.</else> </conditionalvalue></p></then> </conditionalvalue> <conditionalvalue> <istrue><definedclassdocumentation>example</definedclassdocumentation></istrue> <then><heading>Example</heading><p><getclassdocumentation>example</getclassdocumentation></p></then> </conditionalvalue> <p><link> <data>Functions</data> <name>functions</name> </link></p> </forallpublicfunctions> <p><link> <data>Table of contents</data> <name>table_of_contents</name> </link></p> </list> </list> </body> </document>