Add doc comments

Rename test

Author: elsh

include/swift/AST/FileUnit.h

@@ -288,9 +288,11 @@ class FileUnit : public DeclContext, public ASTAllocated<FileUnit> {
     return nullptr;
   }
 
-  /// Returns the name to use when referencing entities in this file.
+  /// Returns the real name of the enclosing module to use when referencing entities in this file.
+  /// The 'real name' is the actual binary name of the module, which can be different from the 'name'
+  /// if module aliasing was used (via -module-alias flag).
   ///
-  /// Usually this is the module name itself, but certain Clang features allow
+  /// Usually this is the module real name itself, but certain Clang features allow
   /// substituting another name instead.
   virtual StringRef getExportedModuleName() const {
     return getParentModule()->getRealName().str();

include/swift/ClangImporter/ClangModule.h

@@ -59,7 +59,7 @@ class ClangModuleUnit final : public LoadedFile {
   ModuleDecl *getOverlayModule() const override;
 
   /// Retrieve the "exported" name of the module, which is usually the module
-  /// name, but might be the name of the public module through which this
+  /// real name, but might be the name of the public module through which this
   /// (private) module is re-exported.
   StringRef getExportedModuleName() const override;
 

lib/AST/Module.cpp

@@ -1499,7 +1499,9 @@ ModuleDecl::ReverseFullNameIterator::ReverseFullNameIterator(
 
 StringRef ModuleDecl::ReverseFullNameIterator::operator*() const {
   assert(current && "all name components exhausted");
-
+  // Return the module's real (binary) name, which can be different from
+  // the name if module aliasing was used (-module-alias flag). The real
+  // name is used for serialization and loading.
   if (auto *swiftModule = current.dyn_cast<const ModuleDecl *>())
     return swiftModule->getRealName().str();
 

lib/ClangImporter/ClangImporter.cpp

@@ -3582,6 +3582,7 @@ StringRef ClangModuleUnit::getExportedModuleName() const {
   if (clangModule && !clangModule->ExportAsModule.empty())
     return clangModule->ExportAsModule;
 
+  // Return module real name (see FileUnit::getExportedModuleName)
   return getParentModule()->getRealName().str();
 }
 

lib/Serialization/Serialization.cpp

@@ -751,6 +751,8 @@ IdentifierID Serializer::addModuleRef(const ModuleDecl *module) {
     return CURRENT_MODULE_ID;
   if (module == this->M->getASTContext().TheBuiltinModule)
     return BUILTIN_MODULE_ID;
+  // Use module 'real name', which can be different from 'name'
+  // in case module aliasing was used (-module-alias flag)
   auto moduleName =
       module->getASTContext().getIdentifier(module->getRealName().str());
   return addDeclBaseNameRef(moduleName);
@@ -961,6 +963,8 @@ void Serializer::writeHeader(const SerializationOptions &options) {
     control_block::RevisionLayout Revision(Out);
     control_block::IsOSSALayout IsOSSA(Out);
 
+    // Write module 'real name', which can be different from 'name'
+    // in case module aliasing is used (-module-alias flag)
     ModuleName.emit(ScratchRecord, M->getRealName().str());
 
     SmallString<32> versionStringBuf;
@@ -1101,6 +1105,9 @@ void Serializer::writeHeader(const SerializationOptions &options) {
 static void flattenImportPath(const ImportedModule &import,
                               SmallVectorImpl<char> &out) {
   llvm::raw_svector_ostream outStream(out);
+  // Write module 'real name' (returned by getReverseFullModuleName),
+  // which can be different from 'name' in case module aliasing was
+  // used (-module-alias flag)
   import.importedModule->getReverseFullModuleName().printForward(
       outStream, StringRef("\0", 1));