On 10 August 2004 23:53, Philip Olson wrote:
> > I'll work on some examples, this is going to be good.
>
> Here's an example where:
>
> * Two new sections: Parameter listing and CHANGELOG
> * The parameter listing is a variablelist
> * The CHANGELOG is a table
>
> http://livedocs.phpp.org/index.php?l=en&q=function.exif-thumbnail
>
> This looks pretty nice except the table has a title and we don't
> need that so next we'll use an informal table. Also, the following
> has a long description that pushes down the parameter listing but
> it doesn't appear to be a major (or common) problem:
>
> http://livedocs.phpp.org/index.php?l=en&q=function.exif-read-data
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!
(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. (Also, if it
were possible to merge the top and bottom dashed borders, that
would be great!) However, I would like to see the type
information repeated here, so I don't have to refer back to the
proto if the associated description doesn't make it obvious to
me (including an & if it's a by-reference parameter).
In keeping with point (i), I'd also prefer these entries to be
a minimal description of purpose, with amplification if necessary
(such as the table for the "sections" parameter in
exif_read_data()) in the long Description section.
(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.
(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.")
> Overall this seems like the way to go.
Yay! Go for it!
Cheers!
Mike
---------------------------------------------------------------------
Mike Ford, Electronic Information Services Adviser,
Learning Support Services, Learning & Information Services,
JG125, James Graham Building, Leeds Metropolitan University,
Headingley Campus, LEEDS, LS6 3QS, United Kingdom
Email: [EMAIL PROTECTED]
Tel: +44 113 283 2600 extn 4730 Fax: +44 113 283 3211
