Document aggregate functions better w.r.t. ORDER BY - Mailing list pgsql-hackers

All,

The recent discussion surrounding aggregates and ORDER BY moved me to look over our existing documentation, especially now that we've reworked the function tables, to see what improvements can be had by simply documenting those functions where ORDER BY may change the user-visible output.  I skipped range aggregates for the moment but handled the others on the aggregates page (not window functions).  This includes the float types for sum and avg.

I added a note just before the table linking back to the syntax chapter and describing the newly added rules and syntax choice in the table.

The nuances of floating point math suggest to me that specifying order by for those is in some kind of gray area and so I've marked it optional...any suggestions for wording (or an xref) to explain those nuances or should it just be shown non-optional like the others?  Or not shown at all?

The novelty of my examples is up for bikeshedding.  I didn't want anything too long so a subquery didn't make sense, and I was trying to avoid duplication as well as multiple lines - hence creating a CTE that can be copied onto all of the example queries to produce the noted result.

I added a DISTINCT example to array_agg because it is the first aggregate on the page and so hopefully will be seen during a cursory reading.  Plus, array_agg is the go-to function for doing this kind of experimentation.

David J.

The patch is attached.  A screenshot exemplifying the changes is copied inline and attached.