Hi Folks: In trying to add the procedural style interface to the DateTime docs I went searching for how we currently present stuff that has both object oriented and procedural interfaces. It turns out there is no consistent way of going about it, plus there are some other oddities that would be good to discuss.
1) How to label the OOP methodsynopsis? Here are the current usages: Object oriented style: Object oriented style Object oriented style (method): Object oriented style (method) Object oriented style (constructor): Object oriented style (property): Object oriented style (property) &style.oop; (Though the style.oop entity was mistakenly defined as "Oriented object style", though I just fixed it to "Object oriented style". I suggest we go with &style.oop; (mapping to "Object oriented style") for everything. The parenthetical method/constructor/property are supurfluous because the way the stuff is rendered clearly explains the usage. Similarly, "&style.procedural;" should be substituted for "Procedural style". Does this seem reasonable to you? 2) Where to put the example output? Generally, output for examples is put inside the <example> element. But when both OOP and procedural styles are shown, it's easier to write/maintain one output. Some docs put it in one of the examples, a la http://us3.php.net/manual/en/rararchive.getcomment.php. It's a somewhat inelegant. Some docs put it outside the <example> section. It works, but it looks a little funny without it being offset inside a box. See http://us3.php.net/manual/en/mysqli.affected-rows.php for what I mean. I did a test of putting the output block inside a separate <example> element just above </refsect1>. It works nicely. Does this sound good to everyone? 3) The way properties are documented/rendered in description refsect1's can be better. Take a look at mysqli affected-rows page (same as above link). "mysqli" is in a box on one line and then "int $affected_rows;" is on another row. Right now we mark up the DocBook like this: <classsynopsis> <ooclass><classname>mysqli</classname></ooclass> <fieldsynopsis> <type>int</type><varname>affected_rows</varname> </fieldsynopsis> </classsynopsis> The <classsynopsis> / class name in this section of the output is unnecessary because the class in question is clear from the page title/etc, plus we don't use it for methods. It seems like things would be much clearer if the class name weren't there and it came out something like this: public int $affected_rows DocBook allows the <fieldsynopsis> to go directly into the <refsect1>. So to accomplish this, the DocBook can be written as such: <fieldsynopsis> <modifier>public</modifier> <type>int</type> <varname>affected_rows</varname> </fieldsynopsis> and then add "div.refsect1 div.fieldsynopsis" to line 979 of site.css to get the border around it just like "div.refsect1 div.methodsynopsis". Looks sweet. What do people think? Once we come to agreements on which ways to go, I'll be glad implement them throughout the existing files. Thanks, --Dan -- T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y data intensive web and database programming http://www.AnalysisAndSolutions.com/ 4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409
