Hannes Magnusson wrote:
On Wed, Sep 10, 2008 at 19:13, Anthony Bedford <[EMAIL PROTECTED]> wrote:
Hi,
As requested I've been working on a mockup of a possible change to this
page:
http://www.php.net/manual/en/book.mysqli.php
The mockup can be viewed here (with notes):
http://docsrva.mysql.com/public/test2.html
Except the obvious lack of $ for static variables, and () for
functions, I think this may just work.
OK, I can add those in. Thanks for pointing that out.
As per the Docbook specs, <book> cannot have _content_ so this table
cannot be on book.mysqli.php. We however could make it an <appendix>
which only contains this table (and whatever relevant info needed).
Now the hard part; how to automate this?
If I change the description of mysqli_foo_bar() I don't want to need
to change it in the appendix too. Why? Because the first 4times
everyone would remember to do it, but the 5-8 someone would have to
reply to the commit and mention it and then 9th+ everyone would forget
until the user gets really confused comparing that table to the actual
documentation.
Furthermore when the extension will introduce new function/alias in
the future noone will remember to add it there too (heck, we don't
even remember to add new extension in the correct places, and we have
scripts to do that!)
Agreed. I'm not sure how it can be done yet though.
3) Some methods can have multiple equivalent methods e.g.
mysqli_result->free has mysqli_result->close, and
mysqli_result->free_result.
Is the table in the mockup an exhausting list of all the current
mapping/aliasing between properties, functions and methods? I think
its important to figure out all the possible aliases before
"acceptance".
It wouldn't surprise me if there existed a method, property and two
functions all aliased together.
Yes, I would not be surprised too. I think as we seem to be heading in
approximately the right direction I will go through the mysqli
documentation and complete the mockup table with "real" data. That way I
can hopefully spot any weird cases. We will then be able to see every
scenario, at least for mysqli.
The list 'Aliases and deprecated Mysqli Functions' would be reduced as the
aliases would be in the table. It could become a 'Deprecated Functions' list
or simply removed if felt to be of limited value.
That page is a junk yard were I threw stuff which I had no idea what
was, as you can see in the history of the file it was once called
"Deprecated functions or otherwise wacky stuff.." with a big fat pink
warning "This section is a total chaos and need serious looking into"
=)
OK, I think we could maybe have a table or list just for deprecated
functions. There are not too many of them.
Thanks,
Tony
