Re: improving object oriented / procedural combinations

On Fri, Apr 23, 2010 at 21:17, Daniel Convissor <danielc@analysisandsolutions.com> wrote: > > > On Fri, Apr 23, 2010 at 05:42:14PM +0200, Hannes Magnusson wrote: >> >> > 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.. > > Where is that the case?  The wording/entities in question are for use in The TOC and refname for example do not have () > the description sections and the example sections of pages.  In > descriptions, methods have parameters or void, thus ()'s around them. > In examples, the methods have ()'s and properties don't. > > Standardizing on the one entitiy means there are fewer entities the > authors have to learn/remember, so it makes documentation easier to > write/maintain and improves consistency. Fine >> 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. > > If you're talking about the same <example>, I agree.  If you are talking > about the same <programlisting>, I disagree because it will lengthen and > clutter the example. Take DateTime::setTime() as an example. It has 4 examples, all using the OO way. Duplicating the entire example for the procedural way feels like a useless clutter to me, even if its in a different <example>. Add one example (into the OO <example>) for date_time_set() which is identical to the last ::setTime() example and a comment above it, mentioning it, should be enough. >> > 3) The way properties are documented/rendered in description refsect1's >> > can be better. > ... snip ... >> I thought we had skeletons for this in doc-base/RFC/? > > Yep.  While classsynopsis is great for class overview pages, it's > overkill for property refentries.  What I realy don't like is the > completely disjointed look of the output.  Perhaps the rendering process > can be changed? I suppose.. but your next example looks awesome: >> > public int $affected_rows >> >> Hmmh. >> Unsure what I think about it.. > > Perhaps: >    public int mysqli->affected_rows > > Or if it's static: >    public int mysqli::affected_rows > That looks great (would be mysqli::$affected_rows for static though.. ;)) -Hannes