[clang] docs(clang): add some missing flags (PR #209519)

[Ehren Bendler via cfe-commits]

https://github.com/ebendler updated https://github.com/llvm/llvm-project/pull/209519

>From 11a624e162c2efa3d7339117465835f3d7dbbf92 Mon Sep 17 00:00:00 2001
From: Ehren Bendler <ebendler at nvidia.com>
Date: Tue, 14 Jul 2026 11:40:56 -0400
Subject: [PATCH] docs(clang): add some missing flags The current user-manual
 is missing options that are useful for machine-readable output, such as
 fdiagnostics-format=sarif and fdiagnostics-absolute-paths.

---
 clang/docs/UsersManual.md                     | 51 ++++++++++++++++++-
 .../analyzer/user-docs/CommandLineUsage.rst   | 19 ++++++-
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 756f2784dc076..c2e06cbcbf58b 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -327,7 +327,7 @@ output format of the diagnostics that it generates.
 ```
 
 ```{eval-rst}
-.. option:: -fdiagnostics-format=clang/msvc/vi
+.. option:: -fdiagnostics-format=clang/msvc/vi/sarif
 
    Changes diagnostic output format to better match IDEs and command line tools.
 
@@ -349,6 +349,29 @@ output format of the diagnostics that it generates.
        ::
 
            t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+
+   **sarif**
+       Emit diagnostics as a `SARIF <https://sarifweb.azurewebsites.net/>`_ JSON document.
+       This is useful when diagnostics are consumed by tools, including AI agents.
+       SARIF diagnostics are written to standard error.
+       Suppress the existing SARIF-stability warning and the final diagnostic summary when capturing a standalone JSON document:
+
+       ::
+
+           clang -fsyntax-only -fdiagnostics-format=sarif \
+                 -Wno-sarif-format-unstable -fno-caret-diagnostics \
+                 t.c 2> diagnostics.sarif
+
+       The SARIF diagnostic format is currently unstable.
+```
+
+```{eval-rst}
+.. option:: -fdiagnostics-absolute-paths
+
+   Print absolute paths in diagnostics.
+
+   This option is useful when a diagnostic consumer does not share Clang's current working directory.
+   It resolves symbolic links before printing paths.
 ```
 
 (opt_fdiagnostics-show-option)=
@@ -926,6 +949,32 @@ information can be included in the remarks (see
 These are options that report execution time and consumed memory of different
 compilations steps.
 
+```{eval-rst}
+.. option:: -ftime-report-json
+
+  Print compiler pass timing statistics as a JSON object to standard error.
+  Use this when no compiler diagnostics will also be emitted to standard error, since other diagnostic output would interleave with the JSON:
+
+  .. code-block:: console
+
+    $ clang -O2 -c foo.c -ftime-report-json -o foo.o 2> timing.json
+```
+
+```{eval-rst}
+.. option:: -ftime-trace[=<path>]
+
+  Write a Chrome tracing-format JSON time trace for the compilation.
+  Without a path, Clang derives the JSON filename from the compilation output.
+  A path names the JSON file or a directory that will contain it.
+
+  :option:`-ftime-trace-granularity` sets the minimum recorded duration in microseconds (500 by default).
+  :option:`-ftime-trace-verbose` records additional event details, including source filenames, and can increase the trace size by two to three times.
+
+  .. code-block:: console
+
+    $ clang -c foo.c -ftime-trace=compile-trace.json -o foo.o
+```
+
 ```{eval-rst}
 .. option:: -fproc-stat-report=
 
diff --git a/clang/docs/analyzer/user-docs/CommandLineUsage.rst b/clang/docs/analyzer/user-docs/CommandLineUsage.rst
index 089a8ce68ce0a..6bacb0d4eb6eb 100644
--- a/clang/docs/analyzer/user-docs/CommandLineUsage.rst
+++ b/clang/docs/analyzer/user-docs/CommandLineUsage.rst
@@ -7,6 +7,24 @@ Both provide a way of driving the analyzer, detecting compilation flags, and gen
 CodeChecker is more actively maintained, provides heuristics for working with multiple versions of popular compilers and it also comes with a web-based GUI for viewing, filtering, categorizing and suppressing the results.
 Therefore CodeChecker is recommended in case you need any of the above features or just more customizability in general.
 
+Machine-readable output
+-----------------------
+
+For a direct analysis of a source file, the ``clang`` driver can write a SARIF report that is suitable for automation and AI agents::
+
+  $ clang --analyze --analyzer-output sarif -o report.sarif source.c
+
+``--analyzer-output`` selects the report format.
+The available formats are ``html``, ``plist``, ``plist-multi-file``, ``plist-html``, ``sarif``, ``sarif-html``, and ``text``.
+``sarif`` writes a SARIF JSON report to the path specified by ``-o``; ``sarif-html`` also creates HTML files for interactive inspection.
+The default format is ``plist``.
+
+This direct form analyzes a translation unit.
+For project-wide analysis, use a tool such as CodeChecker or scan-build to drive the individual compiler invocations.
+``scan-build`` can emit a SARIF report for each analyzed translation unit with its ``-sarif`` option::
+
+  $ scan-build -sarif -o reports make
+
 Comparison of CodeChecker and scan-build
 ----------------------------------------
 
@@ -239,4 +257,3 @@ Detailed Usage
 ~~~~~~~~~~~~~~
 
 For extended documentation please refer to the `official site of CodeChecker <https://github.com/Ericsson/codechecker/blob/master/docs/usage.md>`_!
-