RE: [PHP-DOC] Proposal: CHANGELOG

On Wed, 11 Aug 2004, Ford, Mike [LSS] wrote: > Oh, I like these! I have a few comments that I'd like to cast into > the pool for discussion: > > (i) Personally, I'd like to see the Parameter Information and Change > Log before the full description, so I'd go for something like: > > Definition (proto + *short* description of purpose -- the > first para of each of these would suffice) > Parameter List > Change Log > Return Values > Description (the rest of the full description) > > However, YMMV! I agree with this, but Changelog should be last. > (ii) Parameter List: I'd like to see this kept as compact as > possible, so I'd prefer to do without the vertical spacing > between the parameter name and its description. Yes, it's too large now, and please no dashed borders, just stick to the style that was already used on the page. > (iii) The Change Log table has a rather wide first column -- this > may in part be due to the long title, which I think is excessive: > "Version" would be quite sufficient IMO. Agreed. > > (iv) Return Values: fine (but, as an aside, I'd question the wording > of this particular example -- I think it should be a general rule > to quote the principal return value first, with out-of-range > possibilities afterwards, so: "Returns the embedded thumbnail, or > FALSE if the image contains no thumbnail.") yeah! Derick