[clang] [Clang][Docs][NFC] Correct documentation for the CPATH environment variable (PR #129113)

[Tom Honermann via cfe-commits]

https://github.com/tahonermann updated https://github.com/llvm/llvm-project/pull/129113

>From b274bb5ef53ffc13093a5d454295cba21640dc4e Mon Sep 17 00:00:00 2001
From: Tom Honermann <tom.honermann at intel.com>
Date: Thu, 27 Feb 2025 11:54:41 -0800
Subject: [PATCH 1/2] [Clang][Docs][NFC] Correct documentation for the CPATH
 environment variable.

Clang's current documentation for the `CPATH` environment variable states that
paths it specifies are added as system header search paths. The actual behavior
is that such paths are treated as though they were passed via `-I` options at
the end of the driver command line and are thus added as non-system (user)
header search paths. Clang's behavior is consistent with gcc as documented at
https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html#index-CPATH.
This change aligns Clang's documentation with the behavior actually observed.
Additional editorial changes are included to clarify that the related
`C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH`, `OBJC_INCLUDE_PATH`, and
`OBJCPLUS_INCLUDE_PATH` environment variables specify additional paths that are
treated as system header search paths (in contrast to `CPATH`).
---
 clang/docs/CommandGuide/clang.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index ca8176f854729..b63fb699950f1 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -733,16 +733,17 @@ ENVIRONMENT
 
 .. envvar:: CPATH
 
-  If this environment variable is present, it is treated as a delimited list of
-  paths to be added to the default system include path list. The delimiter is
-  the platform dependent delimiter, as used in the PATH environment variable.
-
-  Empty components in the environment variable are ignored.
+  This environment variable specifies additional header file search paths which
+  behave as if they were specified with the :option:`-I\<directory\>` option at
+  the end of the driver command line. Paths are delimited by the platform
+  dependent delimiter as used in the ``PATH`` environment variable. Empty
+  components in the environment variable are ignored.
 
 .. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
 
-  These environment variables specify additional paths, as for :envvar:`CPATH`, which are
-  only used when processing the appropriate language.
+  These environment variables specify additional system header file search
+  paths to be used when processing the corresponding language. Search paths are
+  delimited as for the :envvar:`CPATH` environment variable.
 
 .. envvar:: MACOSX_DEPLOYMENT_TARGET
 

>From 3998ad4defb526ddf19529010c2fa144d05969de Mon Sep 17 00:00:00 2001
From: Tom Honermann <tom.honermann at intel.com>
Date: Thu, 6 Mar 2025 09:02:07 -0800
Subject: [PATCH 2/2] Squash: Addressed review comments from Erich Keane.

---
 clang/docs/CommandGuide/clang.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index b63fb699950f1..984db2693e383 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -733,11 +733,13 @@ ENVIRONMENT
 
 .. envvar:: CPATH
 
-  This environment variable specifies additional header file search paths which
-  behave as if they were specified with the :option:`-I\<directory\>` option at
-  the end of the driver command line. Paths are delimited by the platform
-  dependent delimiter as used in the ``PATH`` environment variable. Empty
-  components in the environment variable are ignored.
+  This environment variable specifies additional (non-system) header search
+  paths to be used to find included header files. These paths are searched after
+  paths specified with the :option:`-I\<directory\>` option, but before any
+  system header search paths. Paths are delimited by the platform dependent
+  delimiter as used in the ``PATH`` environment variable. Empty entries in the
+  delimited path list are ignored. The treatment of empty entries differs from
+  gcc which treats them as specifying the compiler's current working directory.
 
 .. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH