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.
Goba