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

[Tom Honermann via cfe-commits]

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

Clang's [current documentation for the `CPATH` environment variable](https://clang.llvm.org/docs/CommandGuide/clang.html#envvar-CPATH) states that paths it specifies are added as system header search paths. That documentation has been in place and incorrect since it was added in 2009 (via [this commit](https://github.com/llvm/llvm-project/commit/16af476c4229bc4fb66f0bbbe90168bbe9026625)). The actual behavior (see [here](https://github.com/llvm/llvm-project/blob/e5d93100b656df86854b58433816b0b03ef9f231/clang/lib/Driver/ToolChains/Clang.cpp#L1255-L1257)) 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; that has been the behavior since at least 2011 (see [this commit](https://github.com/llvm/llvm-project/commit/8404eb0badf2911f5afe5039c3887919875dcad5). 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`).

>From 07f7327fd43a7ce3eda560c31ce13ba283362748 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] [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..dc8ee3dacf895 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` option at the end of
+  the driver command line. Paths are delimited by the platform dependent
+  delimiter as used in the :envvar:`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