[PATCH] Improve the documentation of the optimization flags

[Sylvestre Ledru]

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

Files:
  docs/tools/clang.pod

Index: docs/tools/clang.pod
===================================================================
--- docs/tools/clang.pod
+++ docs/tools/clang.pod
@@ -7,7 +7,7 @@
 =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,21 +263,57 @@
 
 =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<-02>.
+
+=item B<-O4>
+
+Equivalent to B<-03>.
+
+=item B<-05> and upper
+
+Fall back on B<-O3>.
+
+=back
+
 =item B<-g>
 
 Generate debug information.  Note that Clang debug information works best at
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D2138.1.patch
Type: text/x-patch
Size: 2606 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20131111/06c992d8/attachment.bin>