Re: [PHP-DOC] Conforming documentation style - how to document classes
On Mon, Jun 15, 2009 at 19:26, Philip Olsonphi...@roshambo.org wrote: On Jun 15, 2009, at 1:18 AM, G. T. Stresen-Reuter wrote: 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)? Do you feel like determining what might work best? I really like what Jakup did with the ext/datetime docs. -Hannes
Re: [PHP-DOC] Conforming documentation style - how to document classes
On Jun 15, 2009, at 6:26 PM, Philip Olson wrote: 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? He he he... no! There does seem to be some consensus among class definitions so, keep reading... On Jun 16, 2009, at 9:06 AM, Hannes Magnusson wrote: I really like what Jakup did with the ext/datetime docs. I simply don't know enough about programming and DocBook to be able to opine with any authority. I'll leave the decision on what format to follow to the experts and do my best to implement whatever decision is made. (and FWIW, I recently discovered http://www.php.net/manual/en/extensions.php and have simply stopped using the other categorizations as I find it hard to determine what category the function I'm looking for will be in) 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...) This list is more than big enough to start. It can always be added to! 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 So, if I understand the purpose of docgen, maybe we could start with skeleton functions and classes in PHP and use them to create the skeletons for the documentation? Ted PS: Should I be cc'ing people in addition to replying to the list? Personally I prefer to receive only one email per thread.
[PHP-DOC] Conforming documentation style - how to document classes
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)? Thanks in advance. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] Conforming documentation style - how to document classes
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
