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.
Chagelog affects parameters, return values, and other types of behaviour, so it should be after the description of these IMHO. I am fine with Philip's above suggestion.
Fine with me too.
Because this is such a major deal how about we wait a little while longer, let's say by the arbitrary date of August 16. If no other
problems are seen it'll be go time! Silence assumes happiness. At that time the HOWTO will be rewritten (I'll do it), revised, and then the conversion process will begin. If we start out slow a few
unsuspecting problems (and solutions) may crop up as we only want to do this once. How the curl_setopt() docs will look comes to mind,
same for sprintf().
Ok, let's wait and see. Can you please cook-up an XML template and send it to the list so that everyone can review it before the 16 ?
Thanks in advance
didou
