BUG #13495: Postgres documentation consistently teaches 'bad' practice

The following bug has been logged on the website:

Bug reference:      13495
Logged by:          Graeme Bell
Email address:      grb@skogoglandskap.no
PostgreSQL version: 9.3.9
Operating system:   Linux
Description:

Relates to a current thread on pgsql-performance.

The postgres documentation presently teaches bad practice to new programmers
by failing to use function volatility categories in examples throughout
most/all of the documentation.

Consequently, many new and existing PG users are writing code that performs
poorly and doesn't scale at all, and don't even know it.

For example: count the uses of volatility classes on these pages.

http://www.postgresql.org/docs/9.3/static/plpgsql-structure.html

http://www.postgresql.org/docs/9.3/static/plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS

Proposed solution:

This issue is absolutely critical for performance and scalability of code,
therefore all of the PG example functions, particularly in the first few
chapters of the documentation, could be altered to demonstrate  correctly
written code in terms of good practice for performance and scability.

My feeling is that good practice should be naturally  acquired by the reader
as they read the first 20 pages of the manual.