Improve the documentation of the optimization flags

Reviewers: rafael.espindola, rengolin, hfinkel

Reviewed By: rengolin

CC: cfe-commits

Differential Revision: http://llvm-reviews.chandlerc.com/D2138

llvm-svn: 194405

clang/docs/tools/clang.pod

@@ -7,7 +7,7 @@ clang - the Clang C, C++, and Objective-C compiler
 =head1 SYNOPSIS
 
 B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g>
-  [B<-O0>|B<-O1>|B<-O2>|B<-Os>|B<-Oz>|B<-O3>|B<-Ofast>|B<-O4>]
+  [B<-O0>|B<-O1>|B<-O2>|B<-O3>|B<-Ofast>|B<-Os>|B<-Oz>|B<-O>|B<-O4>]
   B<-W>I<warnings...> B<-pedantic>
   B<-I>I<dir...> B<-L>I<dir...>
   B<-D>I<macro[=defn]>
@@ -263,20 +263,56 @@ may not exist on earlier ones.
 
 =over
 
-=item B<-O0> B<-O1> B<-O2> B<-Os> B<-Oz> B<-O3> B<-Ofast> B<-O4>
+=item B<-O0> B<-O1> B<-O2> B<-O3> B<-Ofast> B<-Os> B<-Oz> B<-O> B<-O4>
 
-Specify which optimization level to use.  B<-O0> means "no optimization": this
-level compiles the fastest and generates the most debuggable code.  B<-O2> is a
-moderate level of optimization which enables most optimizations.  B<-Os> is like
-B<-O2> with extra optimizations to reduce code size.  B<-Oz> is like B<-Os> 
-(and thus B<-O2>), but reduces code size further.  B<-O3> is like B<-O2>,
-except that it enables optimizations that take longer to perform or that may
-generate larger code (in an attempt to make the program run faster).
-B<-Ofast> enables all the optimizations from B<-O3> along with other aggressive
-optimizations that may violate strict compliance with language standards. On
-supported platforms, B<-O4> enables link-time optimization; object files are
-stored in the LLVM bitcode file format and whole program optimization is done at
-link time. B<-O1> is somewhere between B<-O0> and B<-O2>.
+Specify which optimization level to use:
+
+=over
+
+=item B<-O0>
+
+Means "no optimization": this level compiles the fastest and
+generates the most debuggable code.
+
+=item B<-O1>
+
+Somewhere between B<-O0> and B<-O2>.
+
+=item B<-O2>
+
+Moderate level of optimization which enables most optimizations.
+
+=item B<-O3>
+
+Like B<-O2>, except that it enables optimizations that take longer to perform
+or that may generate larger code (in an attempt to make the program run faster).
+
+=item B<-Ofast>
+
+Enables all the optimizations from B<-O3> along with other aggressive
+optimizations that may violate strict compliance with language standards.
+
+=item B<-Os>
+
+Like B<-O2> with extra optimizations to reduce code size.
+
+=item B<-Oz>
+
+Like B<-Os> (and thus B<-O2>), but reduces code size further.
+
+=item B<-O>
+
+Equivalent to B<-O2>.
+
+=item B<-O4>
+
+Equivalent to B<-O3>.
+
+=item B<-O5> and upper
+
+Fall back on B<-O3>.
+
+=back
 
 =item B<-g>