Re: Proposal to document all of Zend and PHP API and SAPIlayers

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 ...