[clang] e4c2875 - [clang][docs] Update CommandLineUsage and UsersManual with some flags (#209519)

[via cfe-commits]

Author: Ehren Bendler
Date: 2026-07-30T15:56:45Z
New Revision: e4c2875c397861ea45a0cca05107d91d7d785d03

URL: https://github.com/llvm/llvm-project/commit/e4c2875c397861ea45a0cca05107d91d7d785d03
DIFF: https://github.com/llvm/llvm-project/commit/e4c2875c397861ea45a0cca05107d91d7d785d03.diff

LOG: [clang][docs] Update CommandLineUsage and UsersManual with some flags (#209519)

The current user-manual is missing implemented options that are useful
for machine-readable output, such as `-fdiagnostics-format=sarif` and
`-fdiagnostics-absolute-paths`.

Added: 
    

Modified: 
    clang/docs/UsersManual.md
    clang/docs/analyzer/user-docs/CommandLineUsage.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index bce811eed283b..397a4e9644dcb 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -307,7 +307,7 @@ API to output colored diagnostics. This option is only used on Windows and
 defaults to off.
 :::
 
-:::{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.
 
@@ -332,6 +332,26 @@ effect on formatting a simple conversion diagnostic, follow:
   ```
   t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
   ```
+
+- **sarif**: Emit diagnostics as a [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) JSON
+  document. SARIF diagnostics are written to standard error.
+
+  `-Wno-sarif-format-unstable -fno-caret-diagnostics` can be added to disable extraeneous
+  prints if a standalone JSON file is desired.
+
+  ```console
+  clang -fdiagnostics-format=sarif -Wno-sarif-format-unstable -fno-caret-diagnostics t.c 2> diagnostics.sarif
+  ```
+
+  The SARIF diagnostic format is currently unstable.
+:::
+
+:::{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)=
@@ -882,6 +902,22 @@ information can be included in the remarks (see
 These are options that report execution time and consumed memory of 
diff erent
 compilations steps.
 
+:::{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.
+
+```console
+$ clang -c foo.c -ftime-trace=compile-trace.json -o foo.o
+```
+:::
+
 :::{option} -fproc-stat-report=
 
 This option requests the driver to print used memory and execution time of each

diff  --git a/clang/docs/analyzer/user-docs/CommandLineUsage.rst b/clang/docs/analyzer/user-docs/CommandLineUsage.rst
index 089a8ce68ce0a..2a119b294c945 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::
+
+  $ 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 scan-build or CodeChecker 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
 ----------------------------------------