Re: [PHP-DOC] Re: PHP documentation authors / editors and license From: Zak Greant (zak <email protected>)
Date: 02/02/03

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 <email protected>> | 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)

-- 
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php