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

hi, On Sun, Apr 7, 2013 at 11:27 AM, Joe Watkins <krakjoe@php.net> wrote: > 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 ... The more I look at this problem (and have looked at it quite a lot of time), the more I think we should enforce one tool for inline docblock. Doxygen or other (I use cxref, small and perfect for C) would do it, generate docs on release/snaps and be done with that. But the current situation simply increases the clue gap between those implementing internal functions and those using them. Btw, I do not blame anyone, we are all lazy, and I am the laziest :) Cheers, -- Pierre @pierrejoye