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.