r194405 - Improve the documentation of the optimization flags

[Sylvestre Ledru]

On 11/11/2013 20:32, Arthur O'Dwyer wrote:
> 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." ;)
That is the original description (which does not make it better, I agree :)
I am open to suggestion.
>> +=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.)
Well, I left it separated because -O4 used to do something (LTO) and it
might be used again in the future (?).
>= -O5 never had any meaning.
Anyway, I saw Chandler's comment, I will fix that.

>
>> +=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."
>
Right, thanks.

Sylvestre