[clang] Clarify documentation for -funique-source-file-names. (PR #135832)

[Peter Collingbourne via cfe-commits]

https://github.com/pcc updated https://github.com/llvm/llvm-project/pull/135832

>From 6d04789998482be11d15e8969c54df0375987a60 Mon Sep 17 00:00:00 2001
From: Peter Collingbourne <peter at pcc.me.uk>
Date: Tue, 15 Apr 2025 11:27:48 -0700
Subject: [PATCH 1/2] =?UTF-8?q?[=F0=9D=98=80=F0=9D=97=BD=F0=9D=97=BF]=20in?=
 =?UTF-8?q?itial=20version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created using spr 1.3.6-beta.1
---
 clang/docs/UsersManual.rst | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d4656a7e63c99..c75e409dde55e 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2301,11 +2301,31 @@ are listed below.
 
    When enabled, allows the compiler to assume that each object file
    passed to the linker has been compiled using a unique source file
-   name. This is useful for reducing link times when doing ThinLTO
+   path. This is useful for reducing link times when doing ThinLTO
    in combination with whole-program devirtualization or CFI.
 
-   A misuse of this flag will generally result in a duplicate symbol
-   error at link time.
+   The full source path passed to the compiler must be unique. This
+   means that, for example, the following is a usage error:
+
+   .. code-block:: console
+
+     $ cd foo
+     $ clang -funique-source-file-names -c foo.c
+     $ cd ../bar
+     $ clang -funique-source-file-names -c foo.c
+     $ cd ..
+     $ clang foo/foo.o bar/foo.o
+    
+   but this is not:
+
+   .. code-block:: console
+
+     $ clang -funique-source-file-names -c foo/foo.c
+     $ clang -funique-source-file-names -c bar/foo.c
+     $ clang foo/foo.o bar/foo.o
+
+   A misuse of this flag will generally either be harmless or result
+   in a duplicate symbol error at link time.
 
 .. option:: -fforce-emit-vtables
 

>From 6895b6c39ed817c4e2f8b16381688ab0bd459d88 Mon Sep 17 00:00:00 2001
From: Peter Collingbourne <peter at pcc.me.uk>
Date: Tue, 15 Apr 2025 12:11:13 -0700
Subject: [PATCH 2/2] Address comment

Created using spr 1.3.6-beta.1
---
 clang/docs/UsersManual.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index c75e409dde55e..69256527f40c9 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2324,8 +2324,8 @@ are listed below.
      $ clang -funique-source-file-names -c bar/foo.c
      $ clang foo/foo.o bar/foo.o
 
-   A misuse of this flag will generally either be harmless or result
-   in a duplicate symbol error at link time.
+   A misuse of this flag may result in a duplicate symbol error at
+   link time.
 
 .. option:: -fforce-emit-vtables