[clang][deps] NFC: Document collector, rename members

[jansvoboda11]

Summary

This patch documents how ModuleDepCollector{,PP} work and what their members store. Also renames somewhat vague MainDeps to FileDeps and Deps to ModularDeps.

Depends on D98943.

[Bigcheese]

Thanks for the cleanup. Code makes more sense now.

clang/include/clang/Tooling/DependencyScanning/ModuleDepCollector.h

void appendCommonModuleArguments(
     llvm::ArrayRef<ModuleID> Modules,
     std::function<StringRef(ModuleID)> LookupPCMPath,
     std::function<const ModuleDeps &(ModuleID)> LookupModuleDeps,
     std::vector<std::string> &Result);
 } // namespace detail
 
 class ModuleDepCollector;
 
+/// Callback that records textual includes and direct modular includes/imports
+/// during preprocessing. At the end of the main file, it also collects
+/// transitive modular dependencies and passes everything to the
+/// \c DependencyConsumer of the parent \c ModuleDepCollector.
 class ModuleDepCollectorPP final : public PPCallbacks {
 public:
   ModuleDepCollectorPP(CompilerInstance &I, ModuleDepCollector &MDC)
       : Instance(I), MDC(MDC) {}
 
   void FileChanged(SourceLocation Loc, FileChangeReason Reason,
                    SrcMgr::CharacteristicKind FileType,
                    FileID PrevFID) override;
   void InclusionDirective(SourceLocation HashLoc, const Token &IncludeTok,
                           StringRef FileName, bool IsAngled,
                           CharSourceRange FilenameRange, const FileEntry *File,
                           StringRef SearchPath, StringRef RelativePath,
                           const Module *Imported,
                           SrcMgr::CharacteristicKind FileType) override;
   void moduleImport(SourceLocation ImportLoc, ModuleIdPath Path,
                     const Module *Imported) override;
 
   void EndOfMainFile() override;
 
 private:
+  /// The compiler instance for the current translation unit.
   CompilerInstance &Instance;
+  /// The parent dependency collector.
   ModuleDepCollector &MDC;
-  llvm::DenseSet<const Module *> DirectDeps;
+  /// Working set of direct modular dependencies.
+  llvm::DenseSet<const Module *> DirectModularDeps;
 
   void handleImport(const Module *Imported);
+
+  /// Traverses the previously collected direct modular dependencies to discover
+  /// transitive modular dependencies and fills the parent \c ModuleDepCollector
+  /// with both.
   void handleTopLevelModule(const Module *M);
   void addAllSubmoduleDeps(const Module *M, ModuleDeps &MD,
                            llvm::DenseSet<const Module *> &AddedModules);
   void addModuleDep(const Module *M, ModuleDeps &MD,
                     llvm::DenseSet<const Module *> &AddedModules);
 };
 
+/// Collects modular and non-modular dependencies of the main file by attaching
+/// \c ModuleDepCollectorPP to the preprocessor.
 class ModuleDepCollector final : public DependencyCollector {
 public:
   ModuleDepCollector(std::unique_ptr<DependencyOutputOptions> Opts,
                      CompilerInstance &I, DependencyConsumer &C);
 
   void attachToPreprocessor(Preprocessor &PP) override;
   void attachToASTReader(ASTReader &R) override;
 
 private:
   friend ModuleDepCollectorPP;
 
+  /// The compiler instance for the current translation unit.
   CompilerInstance &Instance;
+  /// The consumer of collected dependency information.
   DependencyConsumer &Consumer;
+  /// Path to the main source file.
   std::string MainFile;
+  /// The module hash identifying the compilation conditions.
   std::string ContextHash;
-  std::vector<std::string> MainDeps;
-  std::unordered_map<std::string, ModuleDeps> Deps;
+  /// Non-modular file dependencies. This includes the main source file and
+  /// textually included header files.
+  std::vector<std::string> FileDeps;
+  /// Direct and transitive modular dependencies of the main source file.
+  std::unordered_map<std::string, ModuleDeps> ModularDeps;
+  /// Options that control the dependency output generation.
   std::unique_ptr<DependencyOutputOptions> Opts;
 };
 
 } // end namespace dependencies
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_DEPENDENCY_SCANNING_MODULE_DEP_COLLECTOR_H

clang/lib/Tooling/DependencyScanning/ModuleDepCollector.cpp

void ModuleDepCollectorPP::FileChanged(SourceLocation Loc,
 
   SourceManager &SM = Instance.getSourceManager();
 
   // Dependency generation really does want to go all the way to the
   // file entry for a source location to find out what is depended on.
   // We do not want #line markers to affect dependency generation!
   if (Optional<StringRef> Filename =
           SM.getNonBuiltinFilenameForID(SM.getFileID(SM.getExpansionLoc(Loc))))
-    MDC.MainDeps.push_back(
+    MDC.FileDeps.push_back(
         std::string(llvm::sys::path::remove_leading_dotslash(*Filename)));
 }
 
 void ModuleDepCollectorPP::InclusionDirective(
     SourceLocation HashLoc, const Token &IncludeTok, StringRef FileName,
     bool IsAngled, CharSourceRange FilenameRange, const FileEntry *File,
     StringRef SearchPath, StringRef RelativePath, const Module *Imported,
     SrcMgr::CharacteristicKind FileType) {
   if (!File && !Imported) {
     // This is a non-modular include that HeaderSearch failed to find. Add it
     // here as `FileChanged` will never see it.
-    MDC.MainDeps.push_back(std::string(FileName));
+    MDC.FileDeps.push_back(std::string(FileName));
   }
   handleImport(Imported);
 }
 
 void ModuleDepCollectorPP::moduleImport(SourceLocation ImportLoc,
                                         ModuleIdPath Path,
                                         const Module *Imported) {
   handleImport(Imported);
 }
 
 void ModuleDepCollectorPP::handleImport(const Module *Imported) {
   if (!Imported)
     return;
 
-  MDC.Deps[MDC.ContextHash + Imported->getTopLevelModule()->getFullModuleName()]
+  const Module *TopLevelModule = Imported->getTopLevelModule();
+  MDC.ModularDeps[MDC.ContextHash + TopLevelModule->getFullModuleName()]
       .ImportedByMainFile = true;
-  DirectDeps.insert(Imported->getTopLevelModule());
+  DirectModularDeps.insert(TopLevelModule);
 }
 
 void ModuleDepCollectorPP::EndOfMainFile() {
   FileID MainFileID = Instance.getSourceManager().getMainFileID();
   MDC.MainFile = std::string(
       Instance.getSourceManager().getFileEntryForID(MainFileID)->getName());
 
-  for (const Module *M : DirectDeps) {
+  for (const Module *M : DirectModularDeps)
     handleTopLevelModule(M);
-  }
 
-  for (auto &&I : MDC.Deps)
+  for (auto &&I : MDC.ModularDeps)
     MDC.Consumer.handleModuleDependency(I.second);
 
-  for (auto &&I : MDC.MainDeps)
+  for (auto &&I : MDC.FileDeps)
     MDC.Consumer.handleFileDependency(*MDC.Opts, I);
 }
 
 void ModuleDepCollectorPP::handleTopLevelModule(const Module *M) {
   assert(M == M->getTopLevelModule() && "Expected top level module!");
 
-  auto ModI = MDC.Deps.insert(
+  auto ModI = MDC.ModularDeps.insert(
       std::make_pair(MDC.ContextHash + M->getFullModuleName(), ModuleDeps{}));
 
   if (!ModI.first->second.ID.ModuleName.empty())
     return;
 
   ModuleDeps &MD = ModI.first->second;
 
   const FileEntry *ModuleMap = Instance.getPreprocessor()