2 files changed, 51 insertions, 14 deletions
diff --git a/clang/docs/ClangCommandLineReference.rst b/clang/docs/ClangCommandLineReference.rst
index 7047cd9bb7b..5b8a96b61b3 100644
--- a/clang/docs/ClangCommandLineReference.rst
+++ b/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
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 62e2575c6b2..87434200e77 100644
--- a/clang/docs/UsersManual.rst
+++ b/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: