[PATCH] [DOC] Documentation for pragma optimize on/off

[Dario Domizioli]

Hi,

Please find attached a documentation patch that details the Clang
extensions to selectively disable optimizations.

I have noticed that attribute `optnone` was not documented from a user's
point of view, so I have documented it first in the same section. Then I
have described the recently submitted support for `#pragma clang optimize
on/off`.

Is it acceptable for the documentation to be this terse? I can potentially
expand on it and write at length about how the pragma affects templates,
functions instanced by macros, class methods, and so on (all the cases that
I have verified in the tests for the change introducing the pragma), but
maybe that level of detail is not necessary.

Also, is it ok for this documentation to be in the Language Extensions
document, or do you think it's relevant enough to be in the User Manual
(maybe under the "Controlling Code Generation" section)?

Cheers,
    Dario Domizioli
    SN Systems - Sony Computer Entertainment Group
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140523/0f997984/attachment.html>
-------------- next part --------------
Index: docs/LanguageExtensions.rst
===================================================================
--- docs/LanguageExtensions.rst	(revision 209515)
+++ docs/LanguageExtensions.rst	(working copy)
@@ -1667,3 +1667,51 @@
 
 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
 with :doc:`MemorySanitizer`.
+
+
+Extensions for selectively disabling optimization
+=================================================
+
+Clang provides a mechanism for selectively disabling optimizations in functions
+and methods.
+
+To disable optimizations in a single function definition, the GNU-style or C++11
+non-standard attribute ``optnone`` can be used.
+
+.. code-block:: c++
+
+  // The following functions will not be optimized
+  // GNU-style attribute
+  __attribute__((optnone)) int foo() {
+    // ... code
+  }
+  // C++11 attribute
+  [[clang::optnone]] int bar() {
+    // ... code
+  }
+
+To facilitate disabling optimization for a range of function definitions, a
+range-based pragma is provided. Its syntax is ``#pragma clang optimize``
+followed by ``off`` or ``on``.
+
+.. code-block:: c++
+
+  // The following functions will be decorated with optnone
+  #pragma clang optimize off
+  int foo() {
+    // ... code
+  }
+
+  int bar() {
+    // ... code
+  }
+  #pragma clang optimize on
+
+All function definitions in the region between an ``off`` and the following
+``on`` will be decorated with the ``optnone`` attribute unless doing so would
+conflict with explicit attributes already present on the function (e.g. the
+ones that control inlining).
+
+Note that a stray ``#pragma clang optimize on`` does not selectively enable
+additional optimizations when compiling at low optimization levels. This feature
+can only be used to selectively disable optimizations.