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