Re: MySQLi documentation page mockup

Hannes Magnusson wrote:

On Wed, Sep 10, 2008 at 19:13, Anthony Bedford <Tony.Bedford@sun.com> 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