[NFC] Bridging: Rework include caveats

Author: AnthonyLatsis

include/swift/AST/ASTBridging.h

@@ -13,13 +13,10 @@
 #ifndef SWIFT_AST_ASTBRIDGING_H
 #define SWIFT_AST_ASTBRIDGING_H
 
-// Do not add other C++/llvm/swift header files here!
-// Function implementations should be placed into ASTBridging.cpp and required header files should be added there.
-//
-// Pure bridging mode does not permit including any C++/llvm/swift headers.
-// See also the comments for `BRIDGING_MODE` in the top-level CMakeLists.txt file.
-//
-
+/// `ASTBridging.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/AST/AccessorKind.h"
 #include "swift/AST/AttrKind.h"
 #include "swift/AST/DiagnosticKind.h"

include/swift/AST/AccessorKind.h

@@ -13,8 +13,10 @@
 #ifndef SWIFT_AST_ACCESSOR_KIND_H
 #define SWIFT_AST_ACCESSOR_KIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `AccessorKind.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 
 namespace swift {

include/swift/AST/AttrKind.h

@@ -17,8 +17,10 @@
 #ifndef SWIFT_ATTRKIND_H
 #define SWIFT_ATTRKIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `AttrKind.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/AST/DiagnosticKind.h

@@ -13,8 +13,10 @@
 #ifndef SWIFT_AST_DIAGNOSTIC_KIND_H
 #define SWIFT_AST_DIAGNOSTIC_KIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `DiagnosticKind.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/AST/DiagnosticList.h

@@ -17,8 +17,10 @@
 #ifndef SWIFT_DIAGNOSTICLIST_H
 #define SWIFT_DIAGNOSTICLIST_H
 
-/// Be *very* careful with what you include here! See include caveats in
-/// `ASTBridging.h`.
+/// `DiagnosticList.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/AST/GenericTypeParamKind.h

@@ -17,8 +17,10 @@
 #ifndef SWIFT_AST_GENERICTYPEPARAMKIND_H
 #define SWIFT_AST_GENERICTYPEPARAMKIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `GenericTypeParamKind.h` is imported into Swift. Be *very* careful with
+/// what you include here and keep these includes minimal!
+///
+/// See include caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/AST/LayoutConstraintKind.h

@@ -13,8 +13,10 @@
 #ifndef SWIFT_LAYOUT_CONSTRAINTKIND_H
 #define SWIFT_LAYOUT_CONSTRAINTKIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `LayoutConstraintKind.h` is imported into Swift. Be *very* careful with
+/// what you include here and keep these includes minimal!
+///
+/// See include caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/AST/PlatformKind.h

@@ -17,8 +17,10 @@
 #ifndef SWIFT_AST_PLATFORM_KIND_H
 #define SWIFT_AST_PLATFORM_KIND_H
 
-/// This header is included in a bridging header. Be *very* careful with what
-/// you include here! See include caveats in `ASTBridging.h`.
+/// `PlatformKind.h` is imported into Swift. Be *very* careful with what you
+/// include here and keep these includes minimal!
+///
+/// See include guidelines and caveats in `BasicBridging.h`.
 #include "swift/Basic/SwiftBridging.h"
 #include <stdint.h>
 

include/swift/Basic/BasicBridging.h

@@ -13,11 +13,13 @@
 #ifndef SWIFT_BASIC_BASICBRIDGING_H
 #define SWIFT_BASIC_BASICBRIDGING_H
 
-// Do not add other C++/llvm/swift header files here!
-// Function implementations should be placed into BasicBridging.cpp and required header files should be added there.
+// Do not add other std/llvm header files here!
+// Function implementations should be placed into BasicBridging.cpp and
+// required header files should be added there.
 //
-// Pure bridging mode does not permit including any C++/llvm/swift headers.
-// See also the comments for `BRIDGING_MODE` in the top-level CMakeLists.txt file.
+// Pure bridging mode does not permit including any std/llvm headers.
+// See also the comments for `BRIDGING_MODE` in the top-level CMakeLists.txt
+// file.
 //
 // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 // !! Do not put any constructors inside an                                   !!

include/swift/Basic/SwiftBridging.h

@@ -11,10 +11,11 @@
 //===----------------------------------------------------------------------===//
 ///
 /// This is a wrapper around `<swift/bridging>` that redefines `SWIFT_NAME` to
-/// accept a string literal, and some other macros in case the header is
-/// unavailable (e.g. during bootstrapping). String literals enable us to
-/// properly format the long Swift declaration names that many of our bridging
-/// functions have.
+/// accept a string literal, and some other helpful macros, including fallbacks
+/// for when `<swift/bridging>` is unavailable (e.g. during bootstrapping).
+///
+/// String literals enable us to properly format the long Swift declaration
+/// names specified via `SWIFT_NAME` that many of our bridging functions have.
 ///
 //===----------------------------------------------------------------------===//