Modify setModuleAliases and lookup

Add examples to documentation comment

Author: elsh

Diff for: include/swift/AST/ASTContext.h

@@ -475,6 +475,9 @@ class ASTContext final {
   Identifier getIdentifier(StringRef Str) const;
 
   /// Convert a given alias map to a map of Identifiers between module aliases and underlying names.
+  /// For example, if '-module-alias A=X -module-alias B=Y' input is passed in, the aliases A and B are
+  /// the names of the imported or referenced modules in source files in the main module, and X and Y
+  /// are the underlying (physical) module names on disk.
   void setModuleAliases(const llvm::StringMap<StringRef> &aliasMap);
 
   /// Retrieve the underlying name given an alias name key.

Diff for: include/swift/AST/Module.h

@@ -172,7 +172,7 @@ class ModuleDecl
   mutable Identifier ModuleABIName;
 
   /// The underlying name for an alias used for this module (if any).
-  mutable Identifier ModuleUnderlyingName;
+  mutable Identifier ModuleRealName;
 
 public:
   /// Produces the components of a given module's full name in reverse order.
@@ -360,9 +360,14 @@ class ModuleDecl
     ModuleABIName = name;
   }
 
-  /// Retrieve the underlying name of the alias (if any) used for this module.
-  /// If no module alias is set, it returns getName().
-  Identifier getUnderlyingName() const;
+  /// Retrieve the actual module name of an alias used for this module (if any).
+  ///
+  /// For example, if '-module-alias Foo=Bar' is passed in when building the main module,
+  /// and this module is (a) not the main module and (b) is named Foo, then it returns
+  /// the real (physically on-disk) module name Bar.
+  ///
+  /// If no module aliasing is set, it will return getName(), i.e. Foo.
+  Identifier getRealName() const;
 
   /// User-defined module version number.
   llvm::VersionTuple UserModuleVersion;
@@ -388,10 +393,10 @@ class ModuleDecl
   ///  module if one exists.
   ModuleDecl *getUnderlyingModuleIfOverlay() const;
 
-  /// If a module alias is used, set the corresponding underlying name,
+  /// If a module alias is used, set the corresponding real name on disk,
   /// which will be used for contents including metadata and mangling.
-  void setUnderlyingName(Identifier name) {
-    ModuleUnderlyingName = name;
+  void setRealName(Identifier name) {
+    ModuleRealName = name;
   }
 
 public:

Diff for: lib/AST/ASTContext.cpp

@@ -1645,7 +1645,9 @@ void ASTContext::addModuleInterfaceChecker(
 void ASTContext::setModuleAliases(const llvm::StringMap<StringRef> &aliasMap) {
   for (auto k: aliasMap.keys()) {
     auto val = aliasMap.lookup(k);
-    ModuleAliasMap[getIdentifier(k)] = getIdentifier(val);
+    if (!val.empty()) {
+      ModuleAliasMap[getIdentifier(k)] = getIdentifier(val);
+    }
   }
 }
 
@@ -1654,7 +1656,7 @@ Identifier ASTContext::lookupModuleAlias(Identifier key) const {
   if (found != ModuleAliasMap.end()) {
     return found->second;
   }
-  return Identifier();
+  return key;
 }
 
 Optional<ModuleDependencies> ASTContext::getModuleDependencies(

Diff for: lib/AST/Module.cpp

@@ -476,7 +476,7 @@ ModuleDecl::ModuleDecl(Identifier name, ASTContext &ctx,
   setImplicit();
   setInterfaceType(ModuleType::get(this));
   setAccess(AccessLevel::Public);
-  setUnderlyingName(ctx.lookupModuleAlias(name));
+  setRealName(ctx.lookupModuleAlias(name));
 
   Bits.ModuleDecl.StaticLibrary = 0;
   Bits.ModuleDecl.TestingEnabled = 0;
@@ -1564,9 +1564,9 @@ ImportedModule::removeDuplicates(SmallVectorImpl<ImportedModule> &imports) {
   imports.erase(last, imports.end());
 }
 
-Identifier ModuleDecl::getUnderlyingName() const {
-    if (!ModuleUnderlyingName.empty())
-        return ModuleUnderlyingName;
+Identifier ModuleDecl::getRealName() const {
+    if (!ModuleRealName.empty())
+      return ModuleRealName;
     return getName();
 }