On 04/07/2013 12:29 AM, Stas Malyshev wrote:
> Hi!
>
>
>> I'm not really sure how documenting (inline) API functions is really
>> going to be any different to the prototypes we all put on extension
>> functions/methods, or any more time consuming, and I don't see how
>> randomness comes into it.
>
> Just listing function args is not enough usually - in the manual,
> functions that have just protos are almost as good as undocumented. I of
> course have a bit of skewed point of view - for me, proto is not needed
> for API function because I can just look up the function definition
> right in the source. But maybe for somebody it would be helpful.
>
>> I understand having no time but then these are files we all read and
>> work with, I don't really understand not being able to take an extra 5
>> minutes here and there when we are already engaged in working with the
>> source.
>
> It's not the question of ability, it's the question of a) if it's useful
> and b) having accepted format for doing it.
Stas,
It is useful if we define the accepted format and encourage people
to include useful information, clearly you can look at a function and
know it's prototype immediately, but there's no way you know of all 1000
functions, how on earth do you search for a function you do not even
know exists.
Assuming you find it, which 800/1000 times you will not, reading a
prototype doesn't give you all the information you need, it doesn't give
you anything. You always end up having to read the source code, where it
could be explained in one/two English sentence(s) which your eyes can
process at the same time as reading the prototype itself ...
I cannot believe it's taken so much discussion just to get nowhere,
all I wanted was for someone to take the lead and say "use this
standard/format/software", "you may/may not edit headers", "we will
deploy the documentation at http://"; ... I give up ...
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
