Req #7869 [Opn]: [patch] MDB2 additions

Edit report at http://pear.php.net/bugs/bug.php?id=7869&edit=1 ID: 7869 Updated by: lsmith@php.net Reported By: tgreiser at montana dot com Status: Open Id: 7869 Type: Feature/Change Request Package: Documentation Operating System: N/A PHP Version: Irrelevant New Comment: 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? Previous Comments: ------------------------------------------------------------------------ [2006-06-13 23:06:15] tgreiser at montana dot com 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. ------------------------------------------------------------------------ [2006-06-13 02:41:34] lsmith at php dot net 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?? ------------------------------------------------------------------------ [2006-06-13 02:11:29] takagi at php dot net 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 ------------------------------------------------------------------------ [2006-06-13 01:40:55] tgreiser at montana dot com Here is an incremental patch -p1 with the missing files. http://prim8.net/files/peardoc-mdb2-additions-20060612-incremental.patch ------------------------------------------------------------------------ [2006-06-12 17:40:30] takagi at php dot net I prefer an incremental patch (of course I accept both). ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at http://pear.php.net/bugs/bug.php?id=7869 -- Edit this bug report at http://pear.php.net/bugs/bug.php?id=7869&edit=1