Comments in DebugInfoMetadata.h

Author: dzhidzhoev

llvm/include/llvm/IR/DebugInfoMetadata.h

@@ -2596,15 +2596,35 @@ class DISubprogram : public DILocalScope {
           [](auto *N) { llvm_unreachable("Unexpected retained node!"); });
   }
 
-  /// Remove types that do not belong to the subprogram's scope from
-  /// retainedNodes list.
+  /// When IR modules are merged, typically during LTO, the merged module
+  /// may contain several types having the same linkageName. They are
+  /// supposed to represent the same type included by multiple source code
+  /// files from a single header file.
+  ///
+  /// DebugTypeODRUniquing feature uniques (deduplicates) such types
+  /// based on their linkageName during metadata loading, to speed up
+  /// compilation and reduce debug info size.
+  ///
+  /// However, since function-local types are tracked in DISubprogram's
+  /// retainedNodes field, a single local type may be referenced by multiple
+  /// DISubprograms via retainedNodes as the result of DebugTypeODRUniquing.
+  /// But retainedNodes field of a DISubprogram is meant to hold only
+  /// subprogram's own local entities, therefore such references may
+  /// cause crashes.
+  ///
+  /// To address this problem, this method is called for each new subprogram
+  /// after module loading. It removes references to types belonging
+  /// to other DISubprograms from a subprogram's retainedNodes list.
+  /// If a corresponding IR function refers to local scopes from another
+  /// subprogram, emitted debug info (i.e. DWARF) should rely
+  /// on cross-subprogram references (and cross-CU references, as subprograms
+  /// may belong to different compile units). This is also a drawback:
+  /// when a subprogram refers to types that are local to another subprogram,
+  /// it is more complicated for debugger to properly discover local types
+  /// of a current scope for expression evaluation.
   void cleanupRetainedNodes();
 
-  /// When DebugTypeODRUniquing is enabled, after multiple modules are loaded,
-  /// some subprograms (that are from different compilation units, usually)
-  /// may have references to the same local type in their retainedNodes lists.
-  ///
-  /// Clean up such references.
+  /// Calls SP->cleanupRetainedNodes() for a range of DISubprograms.
   template <typename RangeT>
   static void cleanupRetainedNodes(const RangeT &NewDistinctSPs) {
     for (DISubprogram *SP : NewDistinctSPs)