And further to that there is another revision at:
http://docsrva.mysql.com/public/test3.html
I will continue to add content in an effort to find any 'edge' cases.
Thanks,
Tony
Anthony Bedford 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
This is just a simple mockup, you can ignore the colour scheme. :)
Here are the requirements as I understand them:
1) The main purpose is to make it easier to find the correct methods and
functions.
2) The entries will be links to existing documentation pages (which may
also need to be updated).
3) Some methods can have multiple equivalent methods e.g.
mysqli_result->free has mysqli_result->close, and
mysqli_result->free_result.
4) Static and instance data/methods need to be identified. '::'=static,
'->'=instance. This makes it compatible with example code usage.
5) Properties and methods need to be clearly differentiated.
6) Some procedural functions have aliases e.g.
mysqli->character_set_name has the alias mysqli_client_encoding.
7) Need to be able to quickly scan for procedural functions (just scan
down 'Procedural Interface' column).
8) There will need to be several sections to support multiple classes.
The solution I came up with is a simple table that shows the key
information. The entries in the table being links to the actual
documentation for that method/property. Each 'list of links' on the page
referred to above would be replaced by its own table. This means there
would be four tables: MySQLi, MySQLi_STMT, MySQLi_Result, and
MySQLi_Driver.
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.
Now, at this time I don't know whether this is the right way to go, or
whether this can actually be done using the PHP doc system. So feedback
is appreciated. :)
Many thanks,
Tony
----
Tony Bedford, Technical Writer
Database Technology Group, Sun Microsystems
http://sun.com | http://mysql.com
