Re: improving object oriented / procedural combinations

On 22 April 2010 03:28, Daniel Convissor <danielc@analysisandsolutions.com> wrote: > 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? Yes, using just the entities wherever possible seems the best approach to me. > > > 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? I don't think having a new example block just for output makes much semantic sense. How about having multiple <programlisting> elements (one per paradigm) and one <screen> with the &examples.outputs* entities? > > > 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 >