[Remarks][Docs] Enhance documentation for opt-remarks driver options

Add better documentation about the naming scheme, add a few more
explicit descriptions and make the sphinx look better.

Author: francisvm

clang/docs/ClangCommandLineReference.rst

@@ -1699,9 +1699,14 @@ Emit OpenMP code only for SIMD-based constructs.
 
 .. option:: -foperator-arrow-depth=<arg>
 
-.. option:: -foptimization-record-file=<arg>
+.. option:: -foptimization-record-file=<file>
 
-Specify the output name of the file containing the optimization remarks. Implies -fsave-optimization-record. On Darwin platforms, this cannot be used with multiple -arch <arch> options.
+Implies -fsave-optimization-record. On Darwin platforms, this
+  cannot be used with multiple -arch <arch> options.
+
+.. option:: -foptimization-record-passes=<regex>
+
+Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)
 
 .. option:: -foptimize-sibling-calls, -fno-optimize-sibling-calls
 
@@ -1834,6 +1839,12 @@ Turn on loop reroller
 
 Generate a YAML optimization record file
 
+.. program:: clang1
+.. option:: -fsave-optimization-record=<format>
+.. program:: clang
+
+Generate an optimization record file in a specific format.
+
 .. option:: -fseh-exceptions
 
 Use SEH style exceptions

clang/docs/UsersManual.rst

@@ -324,9 +324,10 @@ output format of the diagnostics that it generates.
 
 .. _opt_fsave-optimization-record:
 
-.. option:: -fsave-optimization-record[=<format>]
+.. option:: -f[no-]save-optimization-record[=<format>]
 
-   Write optimization remarks to a separate file.
+   Enable optimization remarks during compilation and write them to a separate
+   file.
 
    This option, which defaults to off, controls whether Clang writes
    optimization reports to a separate file. By recording diagnostics in a file,
@@ -345,20 +346,45 @@ output format of the diagnostics that it generates.
       ``-fsave-optimization-record=bitstream``: A binary format based on LLVM
       Bitstream.
 
+    The output file is controlled by :ref:`-foptimization-record-file <opt_foptimization-record-file>`.
+
+    In the absence of an explicit output file, the file is chosen using the
+    following scheme:
+
+    ``<base>.opt.<format>``
+
+    where ``<base>`` is based on the output file of the compilation (whether
+    it's explicitly specified through `-o` or not) when used with `-c` or `-S`.
+    In other cases, it's based on the input file's stem. For example:
+
+    * ``clang -fsave-optimization-record -c in.c -o out.o`` will generate
+      ``out.opt.yaml``
+
+    * ``clang -fsave-optimization-record in.c -o out`` will generate
+      ``in.opt.yaml``
+
+    Compiling for multiple architectures will use the following scheme:
+
+    ``<base>-<arch>.opt.<format>``
+
+    Note that this is only allowed on Darwin platforms and is incompatible with
+    passing multiple ``-arch <arch>`` options.
+
+    When targeting (Thin)LTO, the base is derived from the output filename, and
+    the extension is not dropped.
+
+    When targeting ThinLTO, the following scheme is used:
+
+    ``<base>.opt.<format>.thin.<num>.<format>``
+
 .. _opt_foptimization-record-file:
 
 **-foptimization-record-file**
-   Control the file to which optimization reports are written.
-
-   When optimization reports are being output (see
-   :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
-   option controls the file to which those reports are written.
+   Control the file to which optimization reports are written. This implies
+   :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`.
 
-   If this option is not used, optimization records are output to a file named
-   after the primary file being compiled. If that's "foo.c", for example,
-   optimization records are output to "foo.opt.yaml". If a specific
-   serialization format is specified, the file will be named
-   "foo.opt.<format>".
+    On Darwin platforms, this is incompatible with passing multiple
+    ``-arch <arch>`` options.
 
 .. _opt_foptimization-record-passes:
 

clang/include/clang/Driver/Options.td

@@ -1800,16 +1800,18 @@ def foperator_arrow_depth_EQ : Joined<["-"], "foperator-arrow-depth=">,
 def fsave_optimization_record : Flag<["-"], "fsave-optimization-record">,
   Group<f_Group>, HelpText<"Generate a YAML optimization record file">;
 def fsave_optimization_record_EQ : Joined<["-"], "fsave-optimization-record=">,
-  Group<f_Group>, HelpText<"Generate an optimization record file in a specific format (default: YAML)">;
+  Group<f_Group>, HelpText<"Generate an optimization record file in a specific format">,
+  MetaVarName<"<format>">;
 def fno_save_optimization_record : Flag<["-"], "fno-save-optimization-record">,
   Group<f_Group>, Flags<[NoArgumentUnused]>;
 def foptimization_record_file_EQ : Joined<["-"], "foptimization-record-file=">,
   Group<f_Group>,
-  HelpText<"Specify the file name of any generated YAML optimization record">;
+  HelpText<"Specify the output name of the file containing the optimization remarks. Implies -fsave-optimization-record. On Darwin platforms, this cannot be used with multiple -arch <arch> options.">,
+  MetaVarName<"<file>">;
 def foptimization_record_passes_EQ : Joined<["-"], "foptimization-record-passes=">,
   Group<f_Group>,
-  HelpText<"Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)">;
-
+  HelpText<"Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)">,
+  MetaVarName<"<regex>">;
 
 def ftest_coverage : Flag<["-"], "ftest-coverage">, Group<f_Group>;
 def fvectorize : Flag<["-"], "fvectorize">, Group<f_Group>,