[NFC] Restyle getTargetSpecificModuleTriple()

* Adds documentation comments.
* Turns redundant cases into comments.
* Removes the else branch in a couple “if (…) return …; else return …;” patterns.

Author: beccadax

include/swift/Basic/Platform.h

@@ -78,7 +78,7 @@ namespace swift {
   /// Computes the normalized target triple used as the most preferred name for
   /// module loading.
   ///
-  /// For platforms with module stability, this canonicalizes architecture,
+  /// For platforms with fat binaries, this canonicalizes architecture,
   /// vendor, and OS names, strips OS versions, and makes inferred environments
   /// explicit. For other platforms, it returns the unmodified triple.
   ///

lib/Basic/Platform.cpp

@@ -11,9 +11,9 @@
 //===----------------------------------------------------------------------===//
 
 #include "swift/Basic/Platform.h"
-#include "llvm/ADT/Triple.h"
-#include "llvm/ADT/StringSwitch.h"
 #include "llvm/ADT/StringExtras.h"
+#include "llvm/ADT/StringSwitch.h"
+#include "llvm/ADT/Triple.h"
 
 using namespace swift;
 
@@ -191,61 +191,106 @@ StringRef swift::getMajorArchitectureName(const llvm::Triple &Triple) {
   }
 }
 
+// The code below is responsible for normalizing target triples into the form
+// used to name target-specific swiftmodule, swiftinterface, and swiftdoc files.
+// If two triples have incompatible ABIs or can be distinguished by Swift #if
+// declarations, they should normalize to different values.
+//
+// This code is only really used on platforms with toolchains supporting fat
+// binaries (a single binary containing multiple architectures). On these
+// platforms, this code should strip unnecessary details from target triple
+// components and map synonyms to canonical values. Even values which don't need
+// any special canonicalization should be documented here as comments.
+//
+// (Fallback behavior does not belong here; it should be implemented in code
+// that calls this function, most importantly in SerializedModuleLoaderBase.)
+//
+// If you're trying to refer to this code to understand how Swift behaves and
+// you're unfamiliar with LLVM internals, here's a cheat sheet for reading it:
+//
+// * llvm::Triple is the type for a target name. It's a bit of a misnomer,
+//   because it can contain three or four values: arch-vendor-os[-environment].
+//
+// * In .Cases and .Case, the last argument is the value the arguments before it
+//   map to. That is, `.Cases("bar", "baz", "foo")` will return "foo" if it sees
+//   "bar" or "baz".
+//
+// * llvm::Optional is similar to a Swift Optional: it either contains a value
+//   or represents the absence of one. `None` is equivalent to `nil`; leading
+//   `*` is equivalent to trailing `!`; conversion to `bool` is a not-`None`
+//   check.
+
 static StringRef
 getArchForAppleTargetSpecificModuleTriple(const llvm::Triple &triple) {
   auto tripleArchName = triple.getArchName();
 
   return llvm::StringSwitch<StringRef>(tripleArchName)
               .Cases("arm64", "aarch64", "arm64")
-              .Case ("armv7s", "armv7s")
-              .Case ("armv7k", "armv7k")
-              .Case ("armv7", "armv7")
-              .Case ("x86_64h", "x86_64h")
               .Cases("x86_64", "amd64", "x86_64")
               .Cases("i386", "i486", "i586", "i686", "i786", "i886", "i986",
                      "i386")
               .Cases("unknown", "", "unknown")
+  // These values are also supported, but are handled by the default case below:
+  //          .Case ("armv7s", "armv7s")
+  //          .Case ("armv7k", "armv7k")
+  //          .Case ("armv7", "armv7")
               .Default(tripleArchName);
 }
 
 static StringRef
 getVendorForAppleTargetSpecificModuleTriple(const llvm::Triple &triple) {
+  // We unconditionally normalize to "apple" because it's relatively common for
+  // build systems to omit the vendor name or use an incorrect one like
+  // "unknown". Most parts of the compiler ignore the vendor, so you might not
+  // notice such a mistake.
+  //
+  // Please don't depend on this behavior--specify 'apple' if you're building
+  // for an Apple platform.
+
+  assert(triple.isOSDarwin() &&
+         "shouldn't normalize non-Darwin triple to 'apple'");
+
   return "apple";
 }
 
 static StringRef
 getOSForAppleTargetSpecificModuleTriple(const llvm::Triple &triple) {
   auto tripleOSName = triple.getOSName();
 
-  // Truncate the OS name before the first digit.
+  // Truncate the OS name before the first digit. "Digit" here is ASCII '0'-'9'.
   auto tripleOSNameNoVersion = tripleOSName.take_until(llvm::isDigit);
 
   return llvm::StringSwitch<StringRef>(tripleOSNameNoVersion)
               .Cases("macos", "macosx", "darwin", "macos")
-              .Case ("ios", "ios")
-              .Case ("tvos", "tvos")
               .Cases("unknown", "", "unknown")
+  // These values are also supported, but are handled by the default case below:
+  //          .Case ("ios", "ios")
+  //          .Case ("tvos", "tvos")
+  //          .Case ("watchos", "watchos")
               .Default(tripleOSNameNoVersion);
 }
 
 static Optional<StringRef>
 getEnvironmentForAppleTargetSpecificModuleTriple(const llvm::Triple &triple) {
   auto tripleEnvironment = triple.getEnvironmentName();
 
-  if (tripleEnvironment == "") {
-    if (swift::tripleIsAnySimulator(triple))
-      return StringRef("simulator");
-    else
-      return None;
-  }
+  // If the environment is empty, infer a "simulator" environment based on the
+  // OS and architecture combination. This feature is deprecated and exists for
+  // backwards compatibility only; build systems should pass the "simulator"
+  // environment explicitly if they know they're building for a simulator.
+  if (tripleEnvironment == "" && swift::tripleIsAnySimulator(triple))
+    return StringRef("simulator");
 
   return llvm::StringSwitch<Optional<StringRef>>(tripleEnvironment)
-              .Case("simulator", StringRef("simulator"))
-              .Case("unknown", None)
+              .Cases("unknown", "", None)
+  // These values are also supported, but are handled by the default case below:
+  //          .Case ("simulator", StringRef("simulator"))
               .Default(tripleEnvironment);
 }
 
 llvm::Triple swift::getTargetSpecificModuleTriple(const llvm::Triple &triple) {
+  // isOSDarwin() returns true for all Darwin-style OSes, including macOS, iOS,
+  // etc.
   if (triple.isOSDarwin()) {
     StringRef newArch = getArchForAppleTargetSpecificModuleTriple(triple);
 
@@ -256,12 +301,15 @@ llvm::Triple swift::getTargetSpecificModuleTriple(const llvm::Triple &triple) {
     Optional<StringRef> newEnvironment =
         getEnvironmentForAppleTargetSpecificModuleTriple(triple);
 
-    if (newEnvironment)
-      return llvm::Triple(newArch, newVendor, newOS, *newEnvironment);
-    else
+    if (!newEnvironment)
+      // Generate an arch-vendor-os triple.
       return llvm::Triple(newArch, newVendor, newOS);
-  } else {
-    return triple;
+
+    // Generate an arch-vendor-os-environment triple.
+    return llvm::Triple(newArch, newVendor, newOS, *newEnvironment);
   }
+
+  // Other platforms get no normalization.
+  return triple;
 }