On Jun 15, 2009, at 1:18 AM, G. T. Stresen-Reuter wrote:
Hi,
I'm not a big contributor (in fact, haven't done much more than test
PhD and send some feedback) but I do work with the raw documentation
quite a bit.
I've found some apparent irregularities in how classes are
documented. For example, the tidy.html has both procedural and OO
versions of the function. The procedural version follows the
convention found in other function definitions but the OO version
seems to be missing the CLASSSYNOPSIS, OOCLASS, etc. elements thus
there is no way to select just the OO methods.
Is there an exemplary class definition in the existing documentation
I could use as a foundation for fixing the structure of the Tidy
classes (and other classes that I periodically run across with odd
structure)?
Greetings Ted,
Do you feel like determining what might work best?
This could begin the process of knowing. Let's list all OOP+Procedural
API extensions then determine the differences, and use one syntax.
This may or may not be a complete list (likely not, but close):
- Date/datetime (toc has both)
- Dir (toc has both (sort of))
- DOM (not really, but domxml is procedural)
- Fileinfo (toc is procedural)
- Intl (toc is oop)
- MaxDB (toc is procedural)
- MySQLi (toc is oop)
- SQLite (toc is procedural)
- Tidy (???)
- XMLWriter (toc is oop)
While some were Procedural but are now OOP (so they differ):
- Imagick (procedural api not listed (which seems fine, as it's dead/
old))
- Tidy? (???)
- Zip (partial procedural exists for BC, needs clearer definition of
difference)
Unsure how to classify some:
- Rar (appears to use both together (weird))
- SimpleXML (not sure why the procedural exists...)
Summary:
- We do it differently per extension, so are inconsistent
- The TOC for these also differ (lists OOP and/or Procedural)
- This is a problem
Notes:
- Eludes to it: http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/method.xml
- Docgen commit to handle it: http://news.php.net/php.doc.cvs/3884
Regards,
Philip
