[clang][documentation][enhancement]Documented Optimization Flags

[ipriyanshi1708]

Summary

Fixes https://github.com/llvm/llvm-project/issues/53681 . Optimization flags are not documented in the Clang documentation. So I have added information about Optimization flags in the documentation.

[aaron.ballman]

We already have documentation for these: https://clang.llvm.org/docs/CommandGuide/clang.html#code-generation-options

I think there's sufficient confusion in this space that we should fix *something*. We have at least three places where we list a lot of command line options and details about them:

https://clang.llvm.org/docs/ClangCommandLineReference.html
https://clang.llvm.org/docs/UsersManual.html#command-line-options
https://clang.llvm.org/docs/CommandGuide/clang.html

I think that if we did anything in this area, it would be to figure out how these documents relate to one another and move information around to the correct places (probably while adding explicit links between the documents). I believe the way these are intended to work is that the command guide is basically the man page for clang, so it should follow the usual manpage style and content amounts, while the command line reference is the table-generated documentation detailing every command line option Clang supports, and the User's Manual is less about command line and more about implementation-defined behavior in general. So I think what I'd prefer is:

• copy the documentation from the user's manual into Options.td so that the full command line reference file will display the information,
• replace the documentation about the command line in the user's manual with a link to the command guide ("For information about command line options, please see <link>.", effectively),
• ensure that the documentation for command line options listed explicitly in the command guide also exists in Options.td for the full command line reference,
• add a link to the full command line reference from the command guide ("For a list of all command line options supported by Clang, please see <link>.", effectively),
• add a new section about documentation to the internals manual to describe this policy of where command line docs should live.

However, @ipriyanshi1708, don't feel like you're obligated to work on any of this unless you feel like it. It's a fair amount of effort that would be split out over quite a few patches that may need some tweaks to correct documentation details that are unclear or no longer accurate.

clang/docs/UsersManual.rst

.. option:: -fbasic-block-sections=[labels, all, list=<arg>, none]
   will create two unique sections for function ``foo`` with the first
   containing the odd numbered basic blocks and the second containing the
   even numbered basic blocks.
 
   Basic block sections allow the linker to reorder basic blocks and enables
   link-time optimizations like whole program inter-procedural basic block
   reordering.
 
+Optimization Flags
+------------------
+
+The optimization flags control the level of optimization that the compiler performs on the code. For example, ``-O1`` enables a set of optimizations that are designed to improve code performance while still maintaining debugging capabilities. ``-Og`` enables optimizations that do not interfere with debugging, while ``-Ofast`` enables more aggressive optimizations that may sacrifice some debugging capabilities in exchange for maximum performance.
+
+You can use these optimization flags with the Clang compiler by specifying them on the command line when invoking the compiler. For example, to compile a C++ source file with the ``-O2`` optimization level, you would run the following command:
+
+  .. code-block:: console
+
+   $ clang++ -O2 myfile.cpp -o myfile
+
+Here are some common optimization flags with basic descriptions for different versions of the Clang compiler:
+
+Clang 3.8 and earlier:
+""""""""""""""""""""""
+
+1. ``-O0``: no optimization
+2. ``-O1``: basic optimization, such as function inlining and constant propagation
+3. ``-O2``: more aggressive optimization, such as loop unrolling and instruction scheduling
+4. ``-O3``: even more aggressive optimization, such as loop vectorization and function cloning
+5. ``-Os``: optimize for code size rather than execution speed
+6. ``-Ofast``: enable all optimizations that do not violate strict standards compliance
+
+Clang 3.9 and later:
+""""""""""""""""""""
+
+1. ``-O0``: no optimization
+2. ``-O1``: basic optimization, such as function inlining and constant propagation
+3. ``-O2``: more aggressive optimization, such as loop unrolling and instruction scheduling
+4. ``-O3``: even more aggressive optimization, such as loop vectorization and function cloning
+5. ``-Os``: optimize for code size rather than execution speed
+6. ``-Ofast``: enable all optimizations that do not violate strict standards compliance
+7. ``-Oz``: like -Os, but with more aggressive optimization for code size
+8. ``-Og``: optimize for debuggability, with minimal optimization that does not interfere with debugging
+
 Profile Guided Optimization
 ---------------------------
 
 Profile information enables better optimization. For example, knowing that a
 branch is taken very frequently helps the compiler make better decisions when
 ordering basic blocks. Knowing that a function ``foo`` is called more
 frequently than another function ``bar`` helps the inliner. Optimization
 levels ``-O2`` and above are recommended for use of profile guided optimization.