> > 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.
I thought about this but here's why I went with one description. First, the short definition (purpose) is already in the refpurpose of the function. Also, writing a summary for each would be a bit too difficult. As far as using just the first para, I think it'd be confusing having it so far apart from the rest of the description as they are often tied together. And something to keep in mind is long descriptions are rare. I agree return values should go after the parameter list. So here's my thoughts on the matter: Description (full) Parameter List Return Values Changelog Examples See Also The changelog has important information, enough so that it should go before the examples. I believe the only part that needs further discussion and thought is the Description. > > (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. I'm not concerned with the look of livedocs right now and it uses the default livedoc style sheets (nothing was altered), just a simple <variablelist>. > > (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. Sounds good. > > > > (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! This is how functions are done currently, except a few, like this one ;) This rule will be added to the HOWTO although IIRC it's listed somewhere. Regards, Philip.
