[WIP][FileCollector] Add doc comments

[jkorous]

Summary

I would like to use FileCollector and figured out I might as well add things that weren't obvious to me as comments/names.

One thing that I still don't get is the function of OverlayRoot. It looks like it's exposing this prefix from VFSWriter but I am not sure why.

[JDevlieghere]

llvm/include/llvm/Support/FileCollector.h

22–40

for the RedirectingFileSystem

24

s/at some point/eventually/

97

I'm not a fan of this rename, for two reasons:

• It is the root of where files are copied.
• It is the root of the RedirectingFileSystem.

[jkorous]

Addressed the comments.

[jkorous]

llvm/include/llvm/Support/FileCollector.h

97

Reverted this part.

llvm/include/llvm/Support/FileCollector.h

 #include "llvm/ADT/StringSet.h"
 #include "llvm/ADT/Twine.h"
 #include "llvm/Support/VirtualFileSystem.h"
 
 #include <mutex>
 
 namespace llvm {
 class FileCollectorFileSystem;
-/// Collects files into a directory and generates a mapping that can be used by
-/// the VFS.
+
+/// Captures file system interaction and generates data to be later replayed
+/// with the RedirectingFileSystem.
+///
+/// For any file that gets accessed we eventually create:
+/// - a copy of the file inside Root
+/// - a record in RedirectingFileSystem mapping that maps:
+///   current real path -> path to the copy in Root
+///
+/// That intent is that later when the mapping is used by RedirectingFileSystem
+/// it simulates the state of FS that we collected.
+///
+/// We generate file copies and mapping lazily - see writeMapping and copyFiles.
+/// We don't try to capture the state of the file at the exact time when it's
+/// accessed. Files might get changed, deleted ... we record only the "final"
+/// state.
+///
+/// In order to preserve the relative topology of files we use their real paths
+/// as relative paths inside of the Root.
 class FileCollector {
 public:
+  /// \p Root is the directory where collected files are will be stored.
+  /// \p OverlayRoot is VFS mapping root.
   /// \p Root directory gets created in copyFiles unless it already exists.
   FileCollector(std::string Root, std::string OverlayRoot);
 
   void addFile(const Twine &file);
   void addDirectory(const Twine &Dir);
 
   /// Write the yaml mapping (for the VFS) to the given file.
   std::error_code writeMapping(StringRef MappingFile);
 
   /// Copy the files into the root directory.
   ///
   /// When StopOnError is true (the default) we abort as soon as one file
   /// cannot be copied. This is relatively common, for example when a file was
   /// removed after it was added to the mapping.
   std::error_code copyFiles(bool StopOnError = true);
 
-  /// Create a VFS that collects all the paths that might be looked at by the
-  /// file system accesses.
+  /// Create a VFS that uses \p Collector to collect files accessed via \p
+  /// BaseFS.
   static IntrusiveRefCntPtr<vfs::FileSystem>
   createCollectorVFS(IntrusiveRefCntPtr<vfs::FileSystem> BaseFS,
                      std::shared_ptr<FileCollector> Collector);
 
 private:
   friend FileCollectorFileSystem;
 
   bool markAsSeen(StringRef Path) {
protected:
 
   llvm::vfs::directory_iterator
   addDirectoryImpl(const llvm::Twine &Dir,
                    IntrusiveRefCntPtr<vfs::FileSystem> FS, std::error_code &EC);
 
   /// Synchronizes access to Seen, VFSWriter and SymlinkMap.
   std::mutex Mutex;
 
-  /// The root directory where files are copied.
+  /// The directory where collected files are copied to in copyFiles().
   std::string Root;
 
   /// The root directory where the VFS overlay lives.
-  std::string OverlayRoot;
+  const std::string OverlayRoot;
 
   /// Tracks already seen files so they can be skipped.
   StringSet<> Seen;
 
   /// The yaml mapping writer.
   vfs::YAMLVFSWriter VFSWriter;
 
   /// Caches RealPath calls when resolving symlinks.
   StringMap<std::string> SymlinkMap;
 };
 
 } // end namespace llvm
 
 #endif // LLVM_SUPPORT_FILE_COLLECTOR_H