Re: PECL/mysqlnd_ms documentation draft looking for review

On Apr 16, 2011, at 9:15 AM, Ulf Wendel wrote: > Hi, > > I've written some documentation for PECL/mysqlnd_ms. I'm seeking for some > feedback/review and advice on publishing the documentation. I should have SVN access to do but... > > PECL/mysqlnd_ms is a replication and load balancing plugin for the mysqlnd library. The plugin > is in prototype/alpha status. > > I've followed instructions to generate a documentation stub from a PECL module and made > quite some additions. I can render the Docbook using phd as XHTML. The XHTML can be found at: > > http://blog.ulf-wendel.de/tmp/book.mysqlnd-ms.html > > The XML files are at: > > http://blog.ulf-wendel.de/tmp/mysqlnd_ms.zip > > The documentation should cover all of todays plugin features. > > Andrey has done a language and spell check of maybe half of it or a bit more. Some parts still > need to be reviewed. > > I can't tell about the quality of the XML. Not sure if I followed the style guide. > > Comments are welcome. > > Thanks, > Ulf Looks good. A few minor issues, most namely using <literal> in places where <function> or <constant> would be more appropriate, and some whitespace issues (one space), here's a quick review: From consants.xml: - <emphasis role="bold"><literal>mysqlnd_ms_is_select()</literal> - <literal>mysqlnd_ms_is_select()</literal> Aside from not needing <emphasis><literal> together, these should use <function> instead of either. - <literal>MYSQLND_MS_QUERY_USE_LAST_USED</literal> Use <constant> for all references to constants. This is done everywhere. From ini.xml: - <literal><link linkend="function.mysqlnd-ms-get-stats">mysqlnd_ms_get_stats()</link></literal> Use <function> for functions, as it'll automagically add the link, bolding and (). From setup.xml - <literal>mysqlnd_ms.ini_file</literal> It should link to the ini settings, so <link linkend="ini.mysqlnd_ms.ini_file">... From versions.xml - It's missing mysqlnd_ms_get_stats(), and I'm guessing the initial version number will be 0.1 for all these (not Unknown) From mysqlnd-ms-get-stats.xml - <literal>PHP</literal> I think simply PHP is fine, no need for <literal> here. - <link linkend="ini.mysqlnd-ms.enable"><literal>mysqlnd_ms.enable</literal></link> Use <function> Also, nice domain name for your email ;) Regards, Philip