Description: ------------ Here is a patch for some MDB2 additions to peardoc. Patch built against CVS on 2006-06-11. Apply with patch -p1. http://prim8.net/files/peardoc-mdb2-additions-20060611.patch

First up: Thank you very much for putting in the effort! Could someone apply the patch and test it for me? I will then go through and check that the entire content is correct. It looks like a great addition from a quick scan.

I applied the patch and build it. -> http://peardoc.m-takagi.org/en/package.database.mdb2.html "make test" claims that there are a few missing-id like the following, but "make" succeed without any warnings. /usr/bin/onsgmls -i lang-en -s ./phpdocxml.dcl manual.xml /usr/bin/onsgmls:./en/package/database/mdb2/mdb2/connect.xml:59:26:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.setoption" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/begintransaction.xml:118:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.intransaction" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/commit.xml:122:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.intransaction" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/rollback.xml:123:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.intransaction" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/begintransaction.xml:122:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.supports" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/commit.xml:126:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.supports" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2-driver-common/rollback.xml:125:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.supports" /usr/bin/onsgmls:./en/package/database/mdb2/mdb2/connect.xml:120:18:X: reference to non-existent ID "package.database.mdb2.mdb2-driver-common.disconnect" make: *** [test] Error 1

I haven't made those pages yet. I will do so and submit another patch. Would you prefer another complete patch against CVS or an incremental patch against the patched version? I will add 'make test' to my patch/build script to avoid any more errors.

I prefer an incremental patch (of course I accept both).

Here is an incremental patch -p1 with the missing files. http://prim8.net/files/peardoc-mdb2-additions-20060612-incremental.patch

Thank you. This time both "make test" and "make" work well. Lukas, could you please check the contents? http://peardoc.m-takagi.org/en/package.database.mdb2.html

There is alot of infos that are currently missing in these patches. A few parameters need explaining here and there (like $force in disconnect() - but that can easily be done later). However after pondering some more the question I have is how the MDB2 docs should be in the end. My initial plan (before other people started to help) was to just provide end user documentation in the form of tutorials and to leave API style documentation to the autogenerated stuff. So for example in that case there would be a transaction tutorial instead of an explanation for each method that would link to the API documentation. There should also be a tutorial on error handling. The stuff about disconnect() would go into the connection tutorial. The options would also be added there probably. There would also be a tutorial on writing portable code, that would cover supports(). However the old DB docs obviously also featured API documentation that was translated (which is not the case for the auto generated docs). So the question to me is do we want to put in the work to add API docs, or do we rather focus on end user documentation? If we apply the patch in the current form, then people will expect that we start covering the rest of the API in the documentation as well. Alternatively if Tim feels like it (otherwise I will put in the time) we could reorganize his valueable content into tutorials. Since I speak english I am obviously slightly biased to the solution with tutorials, since I do not suffer from having to read english only API docs. Is this an acceptable thing to do though (as long as there is the possibility to get translated end user tutorials??

From my perspective I would like to get the MDB2 docs to the same level as the DB docs. The main thing I would like to see is examples in the API docs, whether this is in DocBook or phpDocumentor format does not matter to me. Also, I just read that "phpDocumentor is fully capable of converting in-code API documentation and external tutorials into Docbook XML". So I guess it would make sense to concentrate on tutorials and phpDoc examples, and if DocBook API docs are needed for translations or other purposes, they could be generated. Either way, I won't have a chance to rework anything before the weekend.

Ok, I will check with Greg again on the docbook API generation. I think we can continue to "handcode" the tutorials. If we have tutorials for all apsects we should also have examples for every API call. Maybe we should add an url link to all phpdoc comments to the tutorials where the method is covered? Tim: So you will try to rework your additions as tutorials on the weekend?

This bug has been fixed in CVS. If this was a documentation problem, the fix will appear on pear.php.net by the end of next Sunday (CET). If this was a problem with the pear.php.net website, the change should be live shortly. Otherwise, the fix will appear in the package's next release. Thank you for the report and for helping us make PEAR better. I have just added documentation for the transaction API. This closed the main omissions mentioned in this request.