NFC: Improve comments in SymbolFilePDB.cpp

Mostly this just fixes bad wrapping caused by the reformat, with tiny
changes sprinkled here and there.

llvm-svn: 293336

lldb/source/Plugins/SymbolFile/PDB/SymbolFilePDB.cpp

@@ -125,9 +125,8 @@ uint32_t SymbolFilePDB::GetNumCompileUnits() {
     m_cached_compile_unit_count = compilands->getChildCount();
 
     // The linker can inject an additional "dummy" compilation unit into the
-    // PDB.
+    // PDB. Ignore this special compile unit for our purposes, if it is there.
-    // Ignore this special compile unit for our purposes, if it is there.  It is
+    // It is always the last one.
-    // always the last one.
     auto last_cu = compilands->getChildAtIndex(m_cached_compile_unit_count - 1);
     std::string name = last_cu->getName();
     if (name == "* Linker *")
@@ -187,12 +186,10 @@ bool SymbolFilePDB::ParseCompileUnitSupportFiles(
     return false;
 
   // In theory this is unnecessary work for us, because all of this information
-  // is easily
+  // is easily (and quickly) accessible from DebugInfoPDB, so caching it a
-  // (and quickly) accessible from DebugInfoPDB, so caching it a second time
+  // second time seems like a waste.  Unfortunately, there's no good way around
-  // seems like a waste.
+  // this short of a moderate refactor since SymbolVendor depends on being able
-  // Unfortunately, there's no good way around this short of a moderate
+  // to cache this list.
-  // refactor, since SymbolVendor
-  // depends on being able to cache this list.
   auto cu = m_session_up->getConcreteSymbolById<PDBSymbolCompiland>(
       sc.comp_unit->GetID());
   if (!cu)
@@ -269,9 +266,8 @@ lldb_private::CompilerDecl SymbolFilePDB::GetDeclForUID(lldb::user_id_t uid) {
 lldb_private::CompilerDeclContext
 SymbolFilePDB::GetDeclContextForUID(lldb::user_id_t uid) {
   // PDB always uses the translation unit decl context for everything.  We can
-  // improve this later
+  // improve this later but it's not easy because PDB doesn't provide a high
-  // but it's not easy because PDB doesn't provide a high enough level of type
+  // enough level of type fidelity in this area.
-  // fidelity in this area.
   return *m_tu_decl_ctx_up;
 }
 
@@ -295,30 +291,25 @@ uint32_t SymbolFilePDB::ResolveSymbolContext(
     uint32_t resolve_scope, lldb_private::SymbolContextList &sc_list) {
   if (resolve_scope & lldb::eSymbolContextCompUnit) {
     // Locate all compilation units with line numbers referencing the specified
-    // file.  For example, if
+    // file.  For example, if `file_spec` is <vector>, then this should return
-    // `file_spec` is <vector>, then this should return all source files and
+    // all source files and header files that reference <vector>, either
-    // header files that reference
+    // directly or indirectly.
-    // <vector>, either directly or indirectly.
     auto compilands = m_session_up->findCompilandsForSourceFile(
         file_spec.GetPath(), PDB_NameSearchFlags::NS_CaseInsensitive);
 
-    // For each one, either find get its previously parsed data, or parse it
+    // For each one, either find its previously parsed data or parse it afresh
-    // afresh and add it to
+    // and add it to the symbol context list.
-    // the symbol context list.
     while (auto compiland = compilands->getNext()) {
       // If we're not checking inlines, then don't add line information for this
-      // file unless the FileSpec
+      // file unless the FileSpec matches.
-      // matches.
       if (!check_inlines) {
         // `getSourceFileName` returns the basename of the original source file
-        // used to generate this compiland.
+        // used to generate this compiland.  It does not return the full path.
-        // It does not return the full path.  Currently the only way to get that
+        // Currently the only way to get that is to do a basename lookup to get
-        // is to do a basename lookup to
+        // the IPDBSourceFile, but this is ambiguous in the case of two source
-        // get the IPDBSourceFile, but this is ambiguous in the case of two
+        // files with the same name contributing to the same compiland.  This is
-        // source files with the same name
+        // a moderately extreme edge case, so we consider this OK for now,
-        // contributing to the same compiland.  This is a moderately extreme
+        // although we need to find a long-term solution.
-        // edge case, so we consider this ok
-        // for now, although we need to find a long term solution.
         std::string source_file = compiland->getSourceFileName();
         auto pdb_file = m_session_up->findOneSourceFile(
             compiland.get(), source_file,
@@ -336,8 +327,7 @@ uint32_t SymbolFilePDB::ResolveSymbolContext(
       sc_list.Append(sc);
 
       // If we were asked to resolve line entries, add all entries to the line
-      // table that match the requested
+      // table that match the requested line (or all lines if `line` == 0).
-      // line (or all lines if `line` == 0)
       if (resolve_scope & lldb::eSymbolContextLineEntry)
         ParseCompileUnitLineTable(sc, line);
     }
@@ -396,9 +386,8 @@ uint32_t SymbolFilePDB::FindTypes(
   std::string name_str = name.AsCString();
 
   // If this might be a regex, we have to return EVERY symbol and process them
-  // one by one, which is going
+  // one by one, which is going to destroy performance on large PDB files.  So
-  // to destroy performance on large PDB files.  So try really hard not to use a
+  // try really hard not to use a regex match.
-  // regex match.
   if (name_str.find_first_of("[]?*.-+\\") != std::string::npos)
     FindTypesByRegex(name_str, max_matches, types);
   else
@@ -410,14 +399,11 @@ void SymbolFilePDB::FindTypesByRegex(const std::string &regex,
                                      uint32_t max_matches,
                                      lldb_private::TypeMap &types) {
   // When searching by regex, we need to go out of our way to limit the search
-  // space as much as possible, since
+  // space as much as possible since this searches EVERYTHING in the PDB,
-  // the way this is implemented is by searching EVERYTHING in the PDB and
+  // manually doing regex comparisons.  PDB library isn't optimized for regex
-  // manually doing a regex compare.  PDB
+  // searches or searches across multiple symbol types at the same time, so the
-  // library isn't optimized for regex searches or searches across multiple
-  // symbol types at the same time, so the
   // best we can do is to search enums, then typedefs, then classes one by one,
-  // and do a regex compare against all
+  // and do a regex comparison against each of them.
-  // of them.
   PDB_SymType tags_to_search[] = {PDB_SymType::Enum, PDB_SymType::Typedef,
                                   PDB_SymType::UDT};
   auto global = m_session_up->getGlobalScope();
@@ -442,9 +428,8 @@ void SymbolFilePDB::FindTypesByRegex(const std::string &regex,
       else if (auto class_type = llvm::dyn_cast<PDBSymbolTypeUDT>(result.get()))
         type_name = class_type->getName();
       else {
-        // We're only looking for types that have names.  Skip symbols, as well
+        // We're looking only for types that have names.  Skip symbols, as well
-        // as
+        // as unnamed types such as arrays, pointers, etc.
-        // unnamed types such as arrays, pointers, etc.
         continue;
       }
 
@@ -484,7 +469,7 @@ void SymbolFilePDB::FindTypesByName(const std::string &name,
     case PDB_SymType::Typedef:
       break;
     default:
-      // We're only looking for types that have names.  Skip symbols, as well as
+      // We're looking only for types that have names.  Skip symbols, as well as
       // unnamed types such as arrays, pointers, etc.
       continue;
     }
@@ -553,14 +538,12 @@ lldb::CompUnitSP SymbolFilePDB::ParseCompileUnitForSymIndex(uint32_t id) {
   auto cu = m_session_up->getConcreteSymbolById<PDBSymbolCompiland>(id);
 
   // `getSourceFileName` returns the basename of the original source file used
-  // to generate this compiland.  It does
+  // to generate this compiland.  It does not return the full path.  Currently
-  // not return the full path.  Currently the only way to get that is to do a
+  // the only way to get that is to do a basename lookup to get the
-  // basename lookup to get the
   // IPDBSourceFile, but this is ambiguous in the case of two source files with
-  // the same name contributing to the
+  // the same name contributing to the same compiland. This is a moderately
-  // same compiland. This is a moderately extreme edge case, so we consider this
+  // extreme edge case, so we consider this OK for now, although we need to find
-  // ok for now, although we need to find
+  // a long-term solution.
-  // a long term solution.
   auto file =
       m_session_up->findOneSourceFile(cu.get(), cu->getSourceFileName(),
                                       PDB_NameSearchFlags::NS_CaseInsensitive);
@@ -589,12 +572,9 @@ bool SymbolFilePDB::ParseCompileUnitLineTable(
       sc.comp_unit->GetID());
 
   // LineEntry needs the *index* of the file into the list of support files
-  // returned by
+  // returned by ParseCompileUnitSupportFiles.  But the underlying SDK gives us
-  // ParseCompileUnitSupportFiles.  But the underlying SDK gives us a globally
+  // a globally unique idenfitifier in the namespace of the PDB.  So, we have to
-  // unique
+  // do a mapping so that we can hand out indices.
-  // idenfitifier in the namespace of the PDB.  So, we have to do a mapping so
-  // that we
-  // can hand out indices.
   llvm::DenseMap<uint32_t, uint32_t> index_map;
   BuildSupportFileIdToSupportFileIndexMap(*cu, index_map);
   auto line_table = llvm::make_unique<LineTable>(sc.comp_unit);
@@ -604,8 +584,7 @@ bool SymbolFilePDB::ParseCompileUnitLineTable(
   auto files = m_session_up->getSourceFilesForCompiland(*cu);
 
   // For each source and header file, create a LineSequence for contributions to
-  // the cu
+  // the cu from that file, and add the sequence.
-  // from that file, and add the sequence.
   while (auto file = files->getNext()) {
     std::unique_ptr<LineSequence> sequence(
         line_table->CreateLineSequenceContainer());
@@ -628,13 +607,12 @@ bool SymbolFilePDB::ParseCompileUnitLineTable(
       uint32_t source_idx = index_map[source_id];
 
       // There was a gap between the current entry and the previous entry if the
-      // addresses don't perfectly line
+      // addresses don't perfectly line up.
-      // up.
       bool is_gap = (i > 0) && (prev_addr + prev_length < addr);
 
       // Before inserting the current entry, insert a terminal entry at the end
-      // of the previous entry's address
+      // of the previous entry's address range if the current entry resulted in
-      // range if the current entry resulted in a gap from the previous entry.
+      // a gap from the previous entry.
       if (is_gap && ShouldAddLine(match_line, prev_line, prev_length)) {
         line_table->AppendLineEntryToSequence(
             sequence.get(), prev_addr + prev_length, prev_line, 0,
@@ -684,14 +662,10 @@ void SymbolFilePDB::BuildSupportFileIdToSupportFileIndexMap(
     const PDBSymbolCompiland &cu,
     llvm::DenseMap<uint32_t, uint32_t> &index_map) const {
   // This is a hack, but we need to convert the source id into an index into the
-  // support
+  // support files array.  We don't want to do path comparisons to avoid
-  // files array.  We don't want to do path comparisons to avoid basename / full
+  // basename / full path issues that may or may not even be a problem, so we
-  // path
+  // use the globally unique source file identifiers.  Ideally we could use the
-  // issues that may or may not even be a problem, so we use the globally unique
+  // global identifiers everywhere, but LineEntry currently assumes indices.
-  // source
-  // file identifiers.  Ideally we could use the global identifiers everywhere,
-  // but LineEntry
-  // currently assumes indices.
   auto source_files = m_session_up->getSourceFilesForCompiland(cu);
   int index = 0;