Hi Hannes:
Thanks for your thorough consideration. Here are some more thoughts...
On Fri, Apr 23, 2010 at 05:42:14PM +0200, Hannes Magnusson wrote:
>
> Wouldn't &style.oop.[[static.]method|ctor|dtor|property]; make more
> sense? Just to make it really clear what it is.
If there were cases where there were multiple OOP interfaces, it makes
sense. But I don't know of any.
As far as putting constructor/destructor in there, the fact that it's a
constructor is pretty clear from the title of the page being
"mysqli::__construct".
> > 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 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.
> I don't see why the example has to use both ways.
> the example should be using "recommended way"
I don't know. It seems to me that if something is doable, we should show
the way to do it.
> 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.
> > 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?
> > 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
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
