Swift: add more comments

Author: AlexDenisov

swift/extractor/BUILD.bazel

@@ -15,6 +15,7 @@ cc_binary(
         "main.cpp",
     ],
     copts = [
+        # Required by LLVM/Swift
         "-fno-rtti",
     ],
     target_compatible_with = select({

swift/extractor/Configuration.h

@@ -6,9 +6,12 @@
 
 namespace codeql {
 struct Configuration {
+  // The location for storing TRAP files to be imported by CodeQL engine.
   std::string trapDir;
+  // The location for storing extracted source files.
   std::string sourceArchiveDir;
-  std::vector<const char*> frontendOptions;
+  // The arguments passed to the extractor. Used for debugging.
+  std::vector<std::string> frontendOptions;
 };
 }  // namespace codeql
 

swift/extractor/Extractor.cpp

@@ -18,11 +18,13 @@ Extractor::Extractor(const Configuration& config, swift::CompilerInstance& insta
     : config{config}, compiler{instance} {}
 
 void Extractor::extract() {
+  // Swift frontend can be called in several different modes, we are interested
+  // only in the cases when either a primary or a main source file is present
   if (compiler.getPrimarySourceFiles().empty()) {
     swift::ModuleDecl* module = compiler.getMainModule();
     if (!module->getFiles().empty() &&
         module->getFiles().front()->getKind() == swift::FileUnitKind::Source) {
-      /// We can only call getMainSourceFile if the first file is of a Source kind
+      // We can only call getMainSourceFile if the first file is of a Source kind
       swift::SourceFile& file = module->getMainSourceFile();
       extractFile(file);
     }
@@ -63,7 +65,10 @@ void Extractor::extractFile(swift::SourceFile& file) {
     return;
   }
 
-  /// TODO: find a more robust approach to avoid collisions?
+  // The extractor can be called several times from different processes with
+  // the same input file(s)
+  // We are using PID to avoid concurrent access
+  // TODO: find a more robust approach to avoid collisions?
   std::string tempTrapName = file.getFilename().str() + '.' + std::to_string(getpid()) + ".trap";
   llvm::SmallString<PATH_MAX> tempTrapPath(config.trapDir);
   llvm::sys::path::append(tempTrapPath, tempTrapName);
@@ -87,12 +92,12 @@ void Extractor::extractFile(swift::SourceFile& file) {
   trap << "#0=*\n";
   trap << "files(#0, " << std::quoted(srcFilePath.str().str()) << ")\n";
 
-  /// TODO: Pick a better name to avoid collisions
+  // TODO: Pick a better name to avoid collisions
   std::string trapName = file.getFilename().str() + ".trap";
   llvm::SmallString<PATH_MAX> trapPath(config.trapDir);
   llvm::sys::path::append(trapPath, trapName);
 
-  /// TODO: The last process wins. Should we do better than that?
+  // TODO: The last process wins. Should we do better than that?
   if (std::error_code ec = llvm::sys::fs::rename(tempTrapPath, trapPath)) {
     std::cerr << "Cannot rename temp trap file '" << tempTrapPath.str().str() << "' -> '"
               << trapPath.str().str() << "': " << ec.message() << "\n";

swift/extractor/Extractor.h

@@ -8,6 +8,7 @@
 
 namespace codeql {
 
+// TODO: add documentation for the class and its public methods
 class Extractor {
  public:
   explicit Extractor(const Configuration& config, swift::CompilerInstance& instance);

swift/extractor/main.cpp

@@ -22,7 +22,7 @@ class Observer : public swift::FrontendObserver {
   const codeql::Configuration& config;
 };
 
-static std::string getenv_default(const char* envvar, const std::string& def) {
+static std::string getenv_or(const char* envvar, const std::string& def) {
   if (const char* var = getenv(envvar)) {
     return var;
   }
@@ -31,28 +31,28 @@ static std::string getenv_default(const char* envvar, const std::string& def) {
 
 int main(int argc, char** argv) {
   if (argc == 1) {
-    /// TODO: print usage
+    // TODO: print usage
     return 1;
   }
-  /// The frontend can be called in different modes, we are only interested
-  /// in -frontend mode
-  /// TODO: filter out at the tracer level
+  // The frontend can be called in different modes, we are only interested
+  // in -frontend mode
+  // TODO: filter out at the tracer level
   if ("-frontend"s != argv[1]) {
     return 0;
   }
   PROGRAM_START(argc, argv);
 
   codeql::Configuration configuration{};
-  configuration.trapDir = getenv_default("CODEQL_EXTRACTOR_SWIFT_TRAP_DIR", ".");
-  configuration.sourceArchiveDir = getenv_default("CODEQL_EXTRACTOR_SWIFT_SOURCE_ARCHIVE_DIR", ".");
+  configuration.trapDir = getenv_or("CODEQL_EXTRACTOR_SWIFT_TRAP_DIR", ".");
+  configuration.sourceArchiveDir = getenv_or("CODEQL_EXTRACTOR_SWIFT_SOURCE_ARCHIVE_DIR", ".");
   std::vector<const char*> args;
   for (int i = 1; i < argc; i++) {
     if ("-frontend"s == argv[i]) {
       continue;
     }
     args.push_back(argv[i]);
   }
-  configuration.frontendOptions = args;
+  std::copy(std::begin(args), std::end(args), std::back_inserter(configuration.frontendOptions));
   Observer observer(configuration);
   int frontend_rc = swift::performFrontend(args, "swift-extractor", (void*)main, &observer);
   llvm::llvm_shutdown();