1. Alas, poor functions...
Many of the design templates don't offer a "function list" anywhere. I suspect this is a holdover from javadoc, caused by the pure object-oriented nature of Java, whereby no function can exist outwith a class. As such, there are class and file lists, but no function lists. When documenting a PHP API, let me tell you in no uncertain terms, this totally sucks!
Sure, the Sloodle API has some object oriented features... but like any normal PHP API, we have standalone functions too! And wouldn't you know it, the only design templates which offer function lists are ones that require frames and/or JavaScript. *sigh*
2. The short end of the tag
The HTML files generated are XHTML, and open with an XML version directive... that is "<?xml ... ?>". No problem. It's actually good standards-compliant stuff! (I like standards compliance.)
Hang on... notice the "<?", otherwise known as a PHP "short tag"?
I myself despise the very existence of PHP short tags, due to this confusion with the XML tags. Normally, however, this should be no problem, since phpdoc only generates static HTML files... right? And nobody in their right mind sets up a server to parse "*.html" files as PHP... right?
In actual fact, the static HTML files generated by phpdoc are named after the file they document... so they become things like "...file.php.html", and for some inexplicable reason, the Plesk software (which administers my virtual private server), sets up Apache to treat any file with a php 'extension' as a PHP script... even if that extension is in the middle of the filename! Nuisance-o-rama!
Added to this fact, PHP by default allows short open tags and (being as I'm running a production server) no error messages normally get displayed, so about 90% of my documentation silently disappeared the moment I uploaded it to my server. It was still on the server, but many of the HTML responses were empty. So after muchos headaches, I eventually caught-on to the dilemma, and solved it with a ".htaccess" file containing but one line:
php_value short_open_tag 0(Arguably, I probably should have used "php_flag", but I was in a bit of a flap at the time to get it done, so nyeh.)
Conclusion
Nuisances aside, it was all round good stuff. I am chuffed to bits with the results, and the "docblock" comment syntax is fairly friendly. It even lets you define you own custom tags, which just get listed with the documentation. Using that feature, I added a "contributor" tag, so that we can have contributor lists in files, rather than "author" (it just seems more appropriate for an open source project that is really community property).
I haven't even mentioned my woes of the "ignore file/directory" list not working quite right, and the utter pest of browser caching to web-development when you're dealing with framesets! But oh well... them's the breaks. XX(
Checkout the initial trial of documentation for Sloodle 0.21:
http://expsloodle.avid-insight.co.uk/docs