Re: improving object oriented / procedural combinations

On Thu, Apr 22, 2010 at 04: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; Wouldn't &style.oop.[[static.]method|ctor|dtor|property]; make more sense? Just to make it really clear what it is. > 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. We don't use () for methods all the time so people _could_ confuse the two... > 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. I don't see why the example has to use both ways. the example should be using "recommended way", if there is any doubt how the oo/procedural method then its fine to have both - but IMO it should be in the same example. > 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. So you want it rendered as $affected_rows? I disagree. Saying that the classname is clear is like saying "no need to mention the mysqli_ prefix, just write affected_rows()". I thought we had skeletons for this in doc-base/RFC/? > 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 Hmmh. Unsure what I think about it.. -Hannes