Re: Re: PHP documentation authors / editors and license

On Sun, Feb 02, 2003 at 09:22:43PM +0100, Maxim Maletsky wrote: ... > > Heh. The content is already in docbook and the user notes are mostly > > useless already. ;) > > I hope you meant they are outdated in some parts. Because, the user > notes are very very usefull for tons of people. It 1) suggests a > function's usage 2) extends the documentation (often they are bugs > and/or what is getting into the official description). Though a cleanup > would be good. Hello Goba and Maxim, Perhaps we don't need to Cc: group or rasmus on this variant of the discussion? :) To be very precise, what I meant was many of the submitted notes are wrong or partially wrong. I understand that some of the notes have significant value. > What I would also like to see in user notes are the examples. Something > that allows someone to choose whether it is a note or this adds an > additional example of usage for the given function. > > Not sure if I render you the idea, but the point is to have a comments > of the function and the code serving as a sample of usage separate and > clearer, perhaps even highlighted. IIRC, there have been a few discussions to separate the notes into categories - tip, example, correction, etc. I think that it was often decided that it was best to just integrate the notes into the documentation periodically. > Also, i think when rethinking the docs we should update the protos where > the return types are confusing. With move from PHP3 to PHP4 many > functions changed to return True and false instead of 1 and -1. This I > addressed in a message a few month ago: > > > http://groups.google.com/groups?q=maxim+maletsky+phpdoc&start=10&hl=en&lr=&ie=UTF-8&oe=UTF-8&selm=20021109043833.EF1C.MAXIM%40php.net&rnum=18 > > the answer I got was: "we've got no time - go ahead". It's kind of a lot > of work here. can we approach it with some more clever method? Is that > important anyway? I'd like this to be fixed, though. > > +1 on all the rest > Cheers! -- Zak Greant <zak@mysql.com> | MySQL Advocate | http://zak.fooassociates.com Developing Dynamic Web Applications with MySQL and PHP MySQL Training: Nuernburg, June 02-06, 2003 Visit http://mysql.com/training for more information Support Global Human Rights - Amnesty International (http://amnesty.org)