[clang] cbea673 - [clang][driver] Restore the original help text for `-I`

[Andrzej Warzynski via cfe-commits]

Author: Andrzej Warzynski
Date: 2021-01-13T09:19:50Z
New Revision: cbea6737d5130724c7c8cf8ee4ccf1c3dd099450

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

LOG: [clang][driver] Restore the original help text for `-I`

The help text for `-I` was recently expanded in [1]. The expanded
version focuses on explaining the semantics of `-I` in Clang. We are now
in the process of adding support for `-I` in Flang and this new
description is incompatible with the semantics of `-I` in Flang. This
was brought up in this review:
  * https://reviews.llvm.org/D93453

This patch reverts the original change in Options.td. This way the help
text for `-I` remains generic enough so that it applies to both Clang
and Flang.

The expanded description of `-I` from [1] is moved to the
`DocBrief` field for `-I`. This field is prioritised over the help text
when generating ClangCommandLineReference.rst, so the user facing
documentation for Clang retains the expanded description:
  * https://clang.llvm.org/docs/ClangCommandLineReference.html
`DocBrief` fields are currently not used in Flang.

As requested in the reviews, the help text and the expanded description
are slightly refined.

[1] Commit: 8dd4e3ceb804a58bcf25e6856fc6fde5e1995a66

Differential Revision: https://reviews.llvm.org/D94169

Added: 
    

Modified: 
    clang/docs/ClangCommandLineReference.rst
    clang/include/clang/Driver/Options.td

Removed: 
    


################################################################################
diff  --git a/clang/docs/ClangCommandLineReference.rst b/clang/docs/ClangCommandLineReference.rst
index ac97f6fed935..d8ad75ce1111 100644
--- a/clang/docs/ClangCommandLineReference.rst
+++ b/clang/docs/ClangCommandLineReference.rst
@@ -1016,7 +1016,12 @@ Flags controlling how ``#include``\s are resolved to files.
 
 .. option:: -I<dir>, --include-directory <arg>, --include-directory=<arg>
 
-Add directory to include search path. If there are multiple -I options, these directories are searched in the order they are given before the standard system directories are searched. If the same directory is in the SYSTEM include search paths, for example if also specified with -isystem, the -I option will be ignored
+Add directory to include search path. For C++ input, if
+there are multiple -I options, these directories are searched
+in the order they are given before the standard system directories
+are searched. If the same directory is in the SYSTEM include search
+paths, for example if also specified with -isystem, the -I option
+will be ignored
 
 .. option:: -I-, --include-barrier
 

diff  --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index b441c1b4c169..acc3db40bdc7 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -651,12 +651,13 @@ def I_ : Flag<["-"], "I-">, Group<I_Group>,
              "remove current directory from include path">;
 def I : JoinedOrSeparate<["-"], "I">, Group<I_Group>,
     Flags<[CC1Option,CC1AsOption]>, MetaVarName<"<dir>">,
-    HelpText<"Add directory to include search path. If there are multiple -I "
-             "options, these directories are searched in the order they are "
-             "given before the standard system directories are searched. "
-             "If the same directory is in the SYSTEM include search paths, for "
-             "example if also specified with -isystem, the -I option will be "
-             "ignored">;
+    HelpText<"Add directory to the end of the list of include search paths">,
+    DocBrief<[{Add directory to include search path. For C++ inputs, if
+there are multiple -I options, these directories are searched
+in the order they are given before the standard system directories
+are searched. If the same directory is in the SYSTEM include search
+paths, for example if also specified with -isystem, the -I option
+will be ignored}]>;
 def L : JoinedOrSeparate<["-"], "L">, Flags<[RenderJoined]>, Group<Link_Group>,
     MetaVarName<"<dir>">, HelpText<"Add directory to library search path">;
 def MD : Flag<["-"], "MD">, Group<M_Group>,