On Sun, 02 Feb 2003 21:33:01 +0100 Gabor Hojtsy <[EMAIL PROTECTED]> wrote:
> > 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.
>
> Huh, I think, I cannot understand what is your point. Would you like to
> provide one selection for user note additions that it is note or example?
Well, I just notice that there are two types of the user notes under the
docs:
1. note on the function (verbal description of something specific)
2. example of usage (PHP code)
the second one, is the code that perhaps wasn't included in our
documentation (because we normally choose generic examples of usage or
because we didn't explain it well) or simply a contribution of short
code by someone.
Wouldn't it be somewhat logical separating them? Why not allow users to
post the sample code creating a series of user contributed samples? As
you know, when you get onto something new (which is why you read the
docs) a sample code usually talks for itself. Just look at the user
notes for RegEx-related functions - people there fight what parses an
email better and so on.
Not sure how this can be organized, maybe with a section right below the
documented function or by marking the notes separately or a whole
another page?
Point is to add more code samples to functions so people get started faster.
This would be helpful and original, though, this wouldn't add us too
much more work as almost most of the notes get some code in it anyway,
it is only not organized.
> > 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.
>
> I have heard some rumors about someone creating a proto check script to
> check whether the protos in phpdoc reflect the current protos of
> functions in the php source. Take in account undocumented new
> parameters, etc. too... I don't think that anybody can get on this to do
> it manually in any reasonable time...
Would be nice to investigate on this deeper and see whether we can do
something about it. I could go ahead to write a similar script myself.
--
Maxim Maletsky
[EMAIL PROTECTED]
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
