r194405 - Improve the documentation of the optimization flags

[Arthur O'Dwyer]

On Mon, Nov 11, 2013 at 11:04 AM, Sylvestre Ledru <sylvestre at debian.org> wrote:
> Author: sylvestre
> Date: Mon Nov 11 13:04:47 2013
> New Revision: 194405
[...]

> +=item B<-Ofast>
> +
> +Enables all the optimizations from B<-O3> along with other aggressive
> +optimizations that may violate strict compliance with language standards.

FWIW, this isn't a terribly helpful description. I assume it's talking
(mostly?) about -ffast-math, but as it stands I don't think it makes
sense to have an option whose only documentation is "This option may
break your code in undocumented ways." ;)

> +=item B<-O4>
> +
> +Equivalent to B<-O3>.

You can roll this into the following item for "-O5 and higher". As I
understand it, there's no longer anything unique about -O4. (And as
below: I don't think Clang intends to guarantee that -O4 will *always*
be equivalent to -O3.)

> +=item B<-O5> and upper
> +
> +Fall back on B<-O3>.

s/upper/higher/ (or /greater/, your choice).
I would prefer to see this documented as "Currently equivalent to
-O3", since (A) you've sensibly gotten away from the "fall back"
terminology in the code patch itself, and (B) I don't think Clang
intends to guarantee that these options will *always* be equivalent to
-O3. It might even make sense to add an explicit caveat, such as
"These options may be assigned new semantics in future releases."

my $.02,
–Arthur