[llvm] r235345 - DwarfUnit: Cleanup comments

Duncan P. N. Exon Smith dexonsmith at apple.com
Mon Apr 20 13:29:51 PDT 2015


Author: dexonsmith
Date: Mon Apr 20 15:29:51 2015
New Revision: 235345

URL: http://llvm.org/viewvc/llvm-project?rev=235345&view=rev
Log:
DwarfUnit: Cleanup comments

Update comment style in `DwarfUnit`.

  - Drop duplicated comments at definition, and update the comments at
    the declaration where the definition comments looked newer or more
    complete.
  - Drop the `functionName -` prefix.
  - Add `\brief` in a few places.
  - Remove a few comments entirely that weren't adding value (just
    turned the function name and arguments into a sentence).

Modified:
    llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.cpp
    llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.h

Modified: llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.cpp
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.cpp?rev=235345&r1=235344&r2=235345&view=diff
==============================================================================
--- llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.cpp (original)
+++ llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.cpp Mon Apr 20 15:29:51 2015
@@ -64,7 +64,6 @@ bool DIEDwarfExpression::isFrameRegister
 }
 
 
-/// Unit - Unit constructor.
 DwarfUnit::DwarfUnit(unsigned UID, dwarf::Tag UnitTag, DICompileUnit Node,
                      AsmPrinter *A, DwarfDebug *DW, DwarfFile *DWU)
     : UniqueID(UID), CUNode(Node), UnitDie(UnitTag), DebugInfoOffset(0), Asm(A),
@@ -83,7 +82,6 @@ DwarfTypeUnit::DwarfTypeUnit(unsigned UI
     addSectionOffset(UnitDie, dwarf::DW_AT_stmt_list, 0);
 }
 
-/// ~Unit - Destructor for compile unit.
 DwarfUnit::~DwarfUnit() {
   for (unsigned j = 0, M = DIEBlocks.size(); j < M; ++j)
     DIEBlocks[j]->~DIEBlock();
@@ -91,15 +89,11 @@ DwarfUnit::~DwarfUnit() {
     DIELocs[j]->~DIELoc();
 }
 
-/// createDIEEntry - Creates a new DIEEntry to be a proxy for a debug
-/// information entry.
 DIEEntry *DwarfUnit::createDIEEntry(DIE &Entry) {
   DIEEntry *Value = new (DIEValueAllocator) DIEEntry(Entry);
   return Value;
 }
 
-/// getDefaultLowerBound - Return the default lower bound for an array. If the
-/// DWARF version doesn't handle the language, return -1.
 int64_t DwarfUnit::getDefaultLowerBound() const {
   switch (getLanguage()) {
   default:
@@ -180,19 +174,12 @@ static bool isShareableAcrossCUs(const D
          !GenerateDwarfTypeUnits;
 }
 
-/// getDIE - Returns the debug information entry map slot for the
-/// specified debug variable. We delegate the request to DwarfDebug
-/// when the DIE for this MDNode can be shared across CUs. The mappings
-/// will be kept in DwarfDebug for shareable DIEs.
 DIE *DwarfUnit::getDIE(const DebugNode *D) const {
   if (isShareableAcrossCUs(D))
     return DU->getDIE(D);
   return MDNodeToDieMap.lookup(D);
 }
 
-/// insertDIE - Insert DIE into the map. We delegate the request to DwarfDebug
-/// when the DIE for this MDNode can be shared across CUs. The mappings
-/// will be kept in DwarfDebug for shareable DIEs.
 void DwarfUnit::insertDIE(const DebugNode *Desc, DIE *D) {
   if (isShareableAcrossCUs(Desc)) {
     DU->insertDIE(Desc, D);
@@ -201,7 +188,6 @@ void DwarfUnit::insertDIE(const DebugNod
   MDNodeToDieMap.insert(std::make_pair(Desc, D));
 }
 
-/// addFlag - Add a flag that is true.
 void DwarfUnit::addFlag(DIE &Die, dwarf::Attribute Attribute) {
   if (DD->getDwarfVersion() >= 4)
     Die.addValue(Attribute, dwarf::DW_FORM_flag_present, DIEIntegerOne);
@@ -209,8 +195,6 @@ void DwarfUnit::addFlag(DIE &Die, dwarf:
     Die.addValue(Attribute, dwarf::DW_FORM_flag, DIEIntegerOne);
 }
 
-/// addUInt - Add an unsigned integer attribute data and value.
-///
 void DwarfUnit::addUInt(DIE &Die, dwarf::Attribute Attribute,
                         Optional<dwarf::Form> Form, uint64_t Integer) {
   if (!Form)
@@ -224,8 +208,6 @@ void DwarfUnit::addUInt(DIE &Block, dwar
   addUInt(Block, (dwarf::Attribute)0, Form, Integer);
 }
 
-/// addSInt - Add an signed integer attribute data and value.
-///
 void DwarfUnit::addSInt(DIE &Die, dwarf::Attribute Attribute,
                         Optional<dwarf::Form> Form, int64_t Integer) {
   if (!Form)
@@ -239,11 +221,6 @@ void DwarfUnit::addSInt(DIELoc &Die, Opt
   addSInt(Die, (dwarf::Attribute)0, Form, Integer);
 }
 
-/// addString - Add a string attribute data and value. We always emit a
-/// reference to the string pool instead of immediate strings so that DIEs have
-/// more predictable sizes. In the case of split dwarf we emit an index
-/// into another table which gets us the static offset into the string
-/// table.
 void DwarfUnit::addString(DIE &Die, dwarf::Attribute Attribute,
                           StringRef String) {
   if (!isDwoUnit())
@@ -260,8 +237,6 @@ void DwarfUnit::addIndexedString(DIE &Di
   Die.addValue(Attribute, dwarf::DW_FORM_GNU_str_index, Str);
 }
 
-/// addLocalString - Add a string attribute data and value. This is guaranteed
-/// to be in the local string pool instead of indirected.
 void DwarfUnit::addLocalString(DIE &Die, dwarf::Attribute Attribute,
                                StringRef String) {
   const TargetLoweringObjectFile &TLOF = Asm->getObjFileLowering();
@@ -276,8 +251,6 @@ void DwarfUnit::addLocalString(DIE &Die,
   Die.addValue(Attribute, dwarf::DW_FORM_strp, Str);
 }
 
-/// addLabel - Add a Dwarf label attribute data and value.
-///
 void DwarfUnit::addLabel(DIE &Die, dwarf::Attribute Attribute, dwarf::Form Form,
                          const MCSymbol *Label) {
   DIEValue *Value = new (DIEValueAllocator) DIELabel(Label);
@@ -288,8 +261,6 @@ void DwarfUnit::addLabel(DIELoc &Die, dw
   addLabel(Die, (dwarf::Attribute)0, Form, Label);
 }
 
-/// addSectionOffset - Add an offset into a section attribute data and value.
-///
 void DwarfUnit::addSectionOffset(DIE &Die, dwarf::Attribute Attribute,
                                  uint64_t Integer) {
   if (DD->getDwarfVersion() >= 4)
@@ -303,9 +274,6 @@ unsigned DwarfTypeUnit::getOrCreateSourc
                         : getCU().getOrCreateSourceID(FileName, DirName);
 }
 
-/// addOpAddress - Add a dwarf op address data and value using the
-/// form given and an op of either DW_FORM_addr or DW_FORM_GNU_addr_index.
-///
 void DwarfUnit::addOpAddress(DIELoc &Die, const MCSymbol *Sym) {
   if (!DD->useSplitDwarf()) {
     addUInt(Die, dwarf::DW_FORM_data1, dwarf::DW_OP_addr);
@@ -323,8 +291,6 @@ void DwarfUnit::addLabelDelta(DIE &Die,
   Die.addValue(Attribute, dwarf::DW_FORM_data4, Value);
 }
 
-/// addDIEEntry - Add a DIE attribute data and value.
-///
 void DwarfUnit::addDIEEntry(DIE &Die, dwarf::Attribute Attribute, DIE &Entry) {
   addDIEEntry(Die, Attribute, createDIEEntry(Entry));
 }
@@ -354,8 +320,6 @@ void DwarfUnit::addDIEEntry(DIE &Die, dw
                Entry);
 }
 
-/// Create a DIE with the given Tag, add the DIE to its parent, and
-/// call insertDIE if MD is not null.
 DIE &DwarfUnit::createAndAddDIE(unsigned Tag, DIE &Parent, const DebugNode *N) {
   assert(Tag != dwarf::DW_TAG_auto_variable &&
          Tag != dwarf::DW_TAG_arg_variable);
@@ -366,8 +330,6 @@ DIE &DwarfUnit::createAndAddDIE(unsigned
   return Die;
 }
 
-/// addBlock - Add block data.
-///
 void DwarfUnit::addBlock(DIE &Die, dwarf::Attribute Attribute, DIELoc *Loc) {
   Loc->ComputeSize(Asm);
   DIELocs.push_back(Loc); // Memoize so we can call the destructor later on.
@@ -381,8 +343,6 @@ void DwarfUnit::addBlock(DIE &Die, dwarf
   Die.addValue(Attribute, Block->BestForm(), Block);
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, unsigned Line, StringRef File,
                               StringRef Directory) {
   if (Line == 0)
@@ -394,8 +354,6 @@ void DwarfUnit::addSourceLine(DIE &Die,
   addUInt(Die, dwarf::DW_AT_decl_line, None, Line);
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, DIVariable V) {
   assert(V);
 
@@ -403,45 +361,34 @@ void DwarfUnit::addSourceLine(DIE &Die,
                 V->getScope()->getDirectory());
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, DIGlobalVariable G) {
   assert(G);
 
   addSourceLine(Die, G->getLine(), G->getFilename(), G->getDirectory());
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, DISubprogram SP) {
   assert(SP);
 
   addSourceLine(Die, SP->getLine(), SP->getFilename(), SP->getDirectory());
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, const MDType *Ty) {
   assert(Ty);
 
   addSourceLine(Die, Ty->getLine(), Ty->getFilename(), Ty->getDirectory());
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, DIObjCProperty Ty) {
   assert(Ty);
 
   addSourceLine(Die, Ty->getLine(), Ty->getFilename(), Ty->getDirectory());
 }
 
-/// addSourceLine - Add location information to specified debug information
-/// entry.
 void DwarfUnit::addSourceLine(DIE &Die, DINameSpace NS) {
   addSourceLine(Die, NS->getLine(), NS->getFilename(), NS->getDirectory());
 }
 
-/// addRegisterOp - Add register operand.
 bool DwarfUnit::addRegisterOpPiece(DIELoc &TheDie, unsigned Reg,
                                    unsigned SizeInBits, unsigned OffsetInBits) {
   DIEDwarfExpression Expr(*Asm, *this, TheDie);
@@ -449,7 +396,6 @@ bool DwarfUnit::addRegisterOpPiece(DIELo
   return true;
 }
 
-/// addRegisterOffset - Add register offset.
 bool DwarfUnit::addRegisterOffset(DIELoc &TheDie, unsigned Reg,
                                   int64_t Offset) {
   DIEDwarfExpression Expr(*Asm, *this, TheDie);
@@ -510,12 +456,6 @@ bool DwarfUnit::addRegisterOffset(DIELoc
 
    That is what this function does.  */
 
-/// addBlockByrefAddress - Start with the address based on the location
-/// provided, and generate the DWARF information necessary to find the
-/// actual Block variable (navigating the Block struct) based on the
-/// starting location.  Add the DWARF information to the die.  For
-/// more information, read large comment just above here.
-///
 void DwarfUnit::addBlockByrefAddress(const DbgVariable &DV, DIE &Die,
                                      dwarf::Attribute Attribute,
                                      const MachineLocation &Location) {
@@ -668,7 +608,6 @@ static uint64_t getBaseTypeSize(DwarfDeb
   return BaseType->getSizeInBits();
 }
 
-/// addConstantFPValue - Add constant value entry in variable DIE.
 void DwarfUnit::addConstantFPValue(DIE &Die, const MachineOperand &MO) {
   assert(MO.isFPImm() && "Invalid machine operand!");
   DIEBlock *Block = new (DIEValueAllocator) DIEBlock();
@@ -691,19 +630,16 @@ void DwarfUnit::addConstantFPValue(DIE &
   addBlock(Die, dwarf::DW_AT_const_value, Block);
 }
 
-/// addConstantFPValue - Add constant value entry in variable DIE.
 void DwarfUnit::addConstantFPValue(DIE &Die, const ConstantFP *CFP) {
   // Pass this down to addConstantValue as an unsigned bag of bits.
   addConstantValue(Die, CFP->getValueAPF().bitcastToAPInt(), true);
 }
 
-/// addConstantValue - Add constant value entry in variable DIE.
 void DwarfUnit::addConstantValue(DIE &Die, const ConstantInt *CI,
                                  const MDType *Ty) {
   addConstantValue(Die, CI->getValue(), Ty);
 }
 
-/// addConstantValue - Add constant value entry in variable DIE.
 void DwarfUnit::addConstantValue(DIE &Die, const MachineOperand &MO,
                                  const MDType *Ty) {
   assert(MO.isImm() && "Invalid machine operand!");
@@ -722,7 +658,6 @@ void DwarfUnit::addConstantValue(DIE &Di
   addConstantValue(Die, Val, isUnsignedDIType(DD, Ty));
 }
 
-// addConstantValue - Add constant value entry in variable DIE.
 void DwarfUnit::addConstantValue(DIE &Die, const APInt &Val, bool Unsigned) {
   unsigned CIBitWidth = Val.getBitWidth();
   if (CIBitWidth <= 64) {
@@ -752,7 +687,6 @@ void DwarfUnit::addConstantValue(DIE &Di
   addBlock(Die, dwarf::DW_AT_const_value, Block);
 }
 
-// Add a linkage name to the DIE.
 void DwarfUnit::addLinkageName(DIE &Die, StringRef LinkageName) {
   if (!LinkageName.empty())
     addString(Die,
@@ -761,7 +695,6 @@ void DwarfUnit::addLinkageName(DIE &Die,
               GlobalValue::getRealLinkageName(LinkageName));
 }
 
-/// addTemplateParams - Add template parameters into buffer.
 void DwarfUnit::addTemplateParams(DIE &Buffer, DIArray TParams) {
   // Add template parameters.
   for (const auto *Element : TParams) {
@@ -772,7 +705,6 @@ void DwarfUnit::addTemplateParams(DIE &B
   }
 }
 
-/// getOrCreateContextDIE - Get context owner's DIE.
 DIE *DwarfUnit::getOrCreateContextDIE(const MDScope *Context) {
   if (!Context || isa<MDFile>(Context))
     return &getUnitDie();
@@ -801,8 +733,6 @@ DIE *DwarfUnit::createTypeDIE(DIComposit
   return &TyDIE;
 }
 
-/// getOrCreateTypeDIE - Find existing DIE or create new DIE for the
-/// given type.
 DIE *DwarfUnit::getOrCreateTypeDIE(const MDNode *TyNode) {
   if (!TyNode)
     return nullptr;
@@ -865,7 +795,6 @@ void DwarfUnit::updateAcceleratorTables(
   }
 }
 
-/// addType - Add a new type attribute to the specified entity.
 void DwarfUnit::addType(DIE &Entity, const MDType *Ty,
                         dwarf::Attribute Attribute) {
   assert(Ty && "Trying to add a type that doesn't exist?");
@@ -887,11 +816,6 @@ void DwarfUnit::addType(DIE &Entity, con
   addDIEEntry(Entity, Attribute, Entry);
 }
 
-/// getParentContextString - Walks the metadata parent chain in a language
-/// specific manner (using the compile unit language) and returns
-/// it as a string. This is done at the metadata level because DIEs may
-/// not currently have been added to the parent context and walking the
-/// DIEs looking for names is more expensive than walking the metadata.
 std::string DwarfUnit::getParentContextString(const MDScope *Context) const {
   if (!Context)
     return "";
@@ -927,7 +851,6 @@ std::string DwarfUnit::getParentContextS
   return CS;
 }
 
-/// constructTypeDIE - Construct basic type die from DIBasicType.
 void DwarfUnit::constructTypeDIE(DIE &Buffer, DIBasicType BTy) {
   // Get core information.
   StringRef Name = BTy->getName();
@@ -946,7 +869,6 @@ void DwarfUnit::constructTypeDIE(DIE &Bu
   addUInt(Buffer, dwarf::DW_AT_byte_size, None, Size);
 }
 
-/// constructTypeDIE - Construct derived type die from DIDerivedType.
 void DwarfUnit::constructTypeDIE(DIE &Buffer, DIDerivedType DTy) {
   // Get core information.
   StringRef Name = DTy->getName();
@@ -976,7 +898,6 @@ void DwarfUnit::constructTypeDIE(DIE &Bu
     addSourceLine(Buffer, DTy);
 }
 
-/// constructSubprogramArguments - Construct function argument DIEs.
 void DwarfUnit::constructSubprogramArguments(DIE &Buffer, DITypeArray Args) {
   for (unsigned i = 1, N = Args.size(); i < N; ++i) {
     const MDType *Ty = resolve(Args[i]);
@@ -992,7 +913,6 @@ void DwarfUnit::constructSubprogramArgum
   }
 }
 
-/// constructTypeDIE - Construct type DIE from DICompositeType.
 void DwarfUnit::constructTypeDIE(DIE &Buffer, DICompositeType CTy) {
   // Add name if not anonymous or intermediate type.
   StringRef Name = CTy->getName();
@@ -1134,8 +1054,6 @@ void DwarfUnit::constructTypeDIE(DIE &Bu
   }
 }
 
-/// constructTemplateTypeParameterDIE - Construct new DIE for the given
-/// DITemplateTypeParameter.
 void DwarfUnit::constructTemplateTypeParameterDIE(DIE &Buffer,
                                                   DITemplateTypeParameter TP) {
   DIE &ParamDIE =
@@ -1147,8 +1065,6 @@ void DwarfUnit::constructTemplateTypePar
     addString(ParamDIE, dwarf::DW_AT_name, TP->getName());
 }
 
-/// constructTemplateValueParameterDIE - Construct new DIE for the given
-/// DITemplateValueParameter.
 void
 DwarfUnit::constructTemplateValueParameterDIE(DIE &Buffer,
                                               DITemplateValueParameter VP) {
@@ -1182,7 +1098,6 @@ DwarfUnit::constructTemplateValueParamet
   }
 }
 
-/// getOrCreateNameSpace - Create a DIE for DINameSpace.
 DIE *DwarfUnit::getOrCreateNameSpace(DINameSpace NS) {
   // Construct the context before querying for the existence of the DIE in case
   // such construction creates the DIE.
@@ -1203,7 +1118,6 @@ DIE *DwarfUnit::getOrCreateNameSpace(DIN
   return &NDie;
 }
 
-/// getOrCreateSubprogramDIE - Create new DIE using SP.
 DIE *DwarfUnit::getOrCreateSubprogramDIE(DISubprogram SP, bool Minimal) {
   // Construct the context before querying for the existence of the DIE in case
   // such construction creates the DIE (as is the case for member function
@@ -1353,7 +1267,6 @@ void DwarfUnit::applySubprogramAttribute
     addFlag(SPDie, dwarf::DW_AT_explicit);
 }
 
-/// constructSubrangeDIE - Construct subrange DIE from DISubrange.
 void DwarfUnit::constructSubrangeDIE(DIE &Buffer, DISubrange SR, DIE *IndexTy) {
   DIE &DW_Subrange = createAndAddDIE(dwarf::DW_TAG_subrange_type, Buffer);
   addDIEEntry(DW_Subrange, dwarf::DW_AT_type, *IndexTy);
@@ -1387,7 +1300,6 @@ DIE *DwarfUnit::getIndexTyDie() {
   return IndexTyDie;
 }
 
-/// constructArrayTypeDIE - Construct array type DIE from DICompositeType.
 void DwarfUnit::constructArrayTypeDIE(DIE &Buffer, DICompositeType CTy) {
   if (CTy->isVector())
     addFlag(Buffer, dwarf::DW_AT_GNU_vector);
@@ -1410,7 +1322,6 @@ void DwarfUnit::constructArrayTypeDIE(DI
   }
 }
 
-/// constructEnumTypeDIE - Construct an enum type DIE from DICompositeType.
 void DwarfUnit::constructEnumTypeDIE(DIE &Buffer, DICompositeType CTy) {
   DIArray Elements = CTy->getElements();
 
@@ -1433,8 +1344,6 @@ void DwarfUnit::constructEnumTypeDIE(DIE
   }
 }
 
-/// constructContainingTypeDIEs - Construct DIEs for types that contain
-/// vtables.
 void DwarfUnit::constructContainingTypeDIEs() {
   for (auto CI = ContainingTypeMap.begin(), CE = ContainingTypeMap.end();
        CI != CE; ++CI) {
@@ -1449,7 +1358,6 @@ void DwarfUnit::constructContainingTypeD
   }
 }
 
-/// constructMemberDIE - Construct member DIE from DIDerivedType.
 void DwarfUnit::constructMemberDIE(DIE &Buffer, DIDerivedType DT_) {
   // Downcast to MDDerivedType.
   const MDDerivedType *DT = cast<MDDerivedType>(DT_);
@@ -1541,7 +1449,6 @@ void DwarfUnit::constructMemberDIE(DIE &
     addFlag(MemberDie, dwarf::DW_AT_artificial);
 }
 
-/// getOrCreateStaticMemberDIE - Create new DIE for C++ static member.
 DIE *DwarfUnit::getOrCreateStaticMemberDIE(DIDerivedType DT_) {
   const MDDerivedType *DT = cast_or_null<MDDerivedType>(DT_);
   if (!DT)

Modified: llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.h
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.h?rev=235345&r1=235344&r2=235345&view=diff
==============================================================================
--- llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.h (original)
+++ llvm/trunk/lib/CodeGen/AsmPrinter/DwarfUnit.h Mon Apr 20 15:29:51 2015
@@ -63,14 +63,14 @@ public:
 };
 
 //===----------------------------------------------------------------------===//
-/// Unit - This dwarf writer support class manages information associated
-/// with a source file.
+/// This dwarf writer support class manages information associated with a
+/// source file.
 class DwarfUnit {
 protected:
-  /// UniqueID - a numeric ID unique among all CUs in the module
+  /// A numeric ID unique among all CUs in the module
   unsigned UniqueID;
 
-  /// Node - MDNode for the compile unit.
+  /// MDNode for the compile unit.
   DICompileUnit CUNode;
 
   /// Unit debug information entry.
@@ -79,39 +79,39 @@ protected:
   /// Offset of the UnitDie from beginning of debug info section.
   unsigned DebugInfoOffset;
 
-  /// Asm - Target of Dwarf emission.
+  /// Target of Dwarf emission.
   AsmPrinter *Asm;
 
   // Holders for some common dwarf information.
   DwarfDebug *DD;
   DwarfFile *DU;
 
-  /// IndexTyDie - An anonymous type for index type.  Owned by UnitDie.
+  /// An anonymous type for index type.  Owned by UnitDie.
   DIE *IndexTyDie;
 
-  /// MDNodeToDieMap - Tracks the mapping of unit level debug information
-  /// variables to debug information entries.
+  /// Tracks the mapping of unit level debug information variables to debug
+  /// information entries.
   DenseMap<const MDNode *, DIE *> MDNodeToDieMap;
 
-  /// MDNodeToDIEEntryMap - Tracks the mapping of unit level debug information
-  /// descriptors to debug information entries using a DIEEntry proxy.
+  /// Tracks the mapping of unit level debug information descriptors to debug
+  /// information entries using a DIEEntry proxy.
   DenseMap<const MDNode *, DIEEntry *> MDNodeToDIEEntryMap;
 
-  /// DIEBlocks - A list of all the DIEBlocks in use.
+  /// A list of all the DIEBlocks in use.
   std::vector<DIEBlock *> DIEBlocks;
-  
-  /// DIELocs - A list of all the DIELocs in use.
+
+  /// A list of all the DIELocs in use.
   std::vector<DIELoc *> DIELocs;
 
-  /// ContainingTypeMap - This map is used to keep track of subprogram DIEs that
-  /// need DW_AT_containing_type attribute. This attribute points to a DIE that
+  /// This map is used to keep track of subprogram DIEs that need
+  /// DW_AT_containing_type attribute. This attribute points to a DIE that
   /// corresponds to the MDNode mapped with the subprogram DIE.
   DenseMap<DIE *, const DebugNode *> ContainingTypeMap;
 
-  // DIEValueAllocator - All DIEValues are allocated through this allocator.
+  // All DIEValues are allocated through this allocator.
   BumpPtrAllocator DIEValueAllocator;
 
-  // DIEIntegerOne - A preallocated DIEValue because 1 is used frequently.
+  // A preallocated DIEValue because 1 is used frequently.
   DIEInteger *DIEIntegerOne;
 
   /// The section this unit will be emitted in.
@@ -120,8 +120,9 @@ protected:
   DwarfUnit(unsigned UID, dwarf::Tag, DICompileUnit CU, AsmPrinter *A,
             DwarfDebug *DW, DwarfFile *DWU);
 
-
-  /// Add a string attribute data and value.
+  /// \brief Add a string attribute data and value.
+  ///
+  /// This is guaranteed to be in the local string pool instead of indirected.
   void addLocalString(DIE &Die, dwarf::Attribute Attribute, StringRef Str);
 
   void addIndexedString(DIE &Die, dwarf::Attribute Attribute, StringRef Str);
@@ -148,11 +149,16 @@ public:
   unsigned getDebugInfoOffset() const { return DebugInfoOffset; }
   void setDebugInfoOffset(unsigned DbgInfoOff) { DebugInfoOffset = DbgInfoOff; }
 
-  /// hasContent - Return true if this compile unit has something to write out.
+  /// \brief Return true if this compile unit has something to write out.
   bool hasContent() const { return !UnitDie.getChildren().empty(); }
 
-  /// getParentContextString - Get a string containing the language specific
-  /// context for a global name.
+  /// \brief Get string containing language specific context for a global name.
+  ///
+  /// Walks the metadata parent chain in a language specific manner (using the
+  /// compile unit language) and returns it as a string. This is done at the
+  /// metadata level because DIEs may not currently have been added to the
+  /// parent context and walking the DIEs looking for names is more expensive
+  /// than walking the metadata.
   std::string getParentContextString(const MDScope *Context) const;
 
   /// Add a new global name to the compile unit.
@@ -163,77 +169,81 @@ public:
   virtual void addGlobalType(const MDType *Ty, const DIE &Die,
                              const MDScope *Context) {}
 
-  /// addAccelNamespace - Add a new name to the namespace accelerator table.
+  /// \brief Add a new name to the namespace accelerator table.
   void addAccelNamespace(StringRef Name, const DIE &Die);
 
-  /// getDIE - Returns the debug information entry map slot for the
-  /// specified debug variable. We delegate the request to DwarfDebug
-  /// when the MDNode can be part of the type system, since DIEs for
-  /// the type system can be shared across CUs and the mappings are
-  /// kept in DwarfDebug.
+  /// \brief Returns the DIE map slot for the specified debug variable.
+  ///
+  /// We delegate the request to DwarfDebug when the MDNode can be part of the
+  /// type system, since DIEs for the type system can be shared across CUs and
+  /// the mappings are kept in DwarfDebug.
   DIE *getDIE(const DebugNode *D) const;
 
-  /// getDIELoc - Returns a fresh newly allocated DIELoc.
+  /// \brief Returns a fresh newly allocated DIELoc.
   DIELoc *getDIELoc() { return new (DIEValueAllocator) DIELoc(); }
 
-  /// insertDIE - Insert DIE into the map. We delegate the request to DwarfDebug
-  /// when the MDNode can be part of the type system, since DIEs for
-  /// the type system can be shared across CUs and the mappings are
-  /// kept in DwarfDebug.
+  /// \brief Insert DIE into the map.
+  ///
+  /// We delegate the request to DwarfDebug when the MDNode can be part of the
+  /// type system, since DIEs for the type system can be shared across CUs and
+  /// the mappings are kept in DwarfDebug.
   void insertDIE(const DebugNode *Desc, DIE *D);
 
-  /// addFlag - Add a flag that is true to the DIE.
+  /// \brief Add a flag that is true to the DIE.
   void addFlag(DIE &Die, dwarf::Attribute Attribute);
 
-  /// addUInt - Add an unsigned integer attribute data and value.
+  /// \brief Add an unsigned integer attribute data and value.
   void addUInt(DIE &Die, dwarf::Attribute Attribute, Optional<dwarf::Form> Form,
                uint64_t Integer);
 
   void addUInt(DIE &Block, dwarf::Form Form, uint64_t Integer);
 
-  /// addSInt - Add an signed integer attribute data and value.
+  /// \brief Add an signed integer attribute data and value.
   void addSInt(DIE &Die, dwarf::Attribute Attribute, Optional<dwarf::Form> Form,
                int64_t Integer);
 
   void addSInt(DIELoc &Die, Optional<dwarf::Form> Form, int64_t Integer);
 
-  /// addString - Add a string attribute data and value.
+  /// \brief Add a string attribute data and value.
+  ///
+  /// We always emit a reference to the string pool instead of immediate
+  /// strings so that DIEs have more predictable sizes. In the case of split
+  /// dwarf we emit an index into another table which gets us the static offset
+  /// into the string table.
   void addString(DIE &Die, dwarf::Attribute Attribute, StringRef Str);
 
-  /// addLabel - Add a Dwarf label attribute data and value.
+  /// \brief Add a Dwarf label attribute data and value.
   void addLabel(DIE &Die, dwarf::Attribute Attribute, dwarf::Form Form,
                 const MCSymbol *Label);
 
   void addLabel(DIELoc &Die, dwarf::Form Form, const MCSymbol *Label);
 
-  /// addSectionOffset - Add an offset into a section attribute data and value.
-  ///
+  /// \brief Add an offset into a section attribute data and value.
   void addSectionOffset(DIE &Die, dwarf::Attribute Attribute, uint64_t Integer);
 
-  /// addOpAddress - Add a dwarf op address data and value using the
-  /// form given and an op of either DW_FORM_addr or DW_FORM_GNU_addr_index.
+  /// \brief Add a dwarf op address data and value using the form given and an
+  /// op of either DW_FORM_addr or DW_FORM_GNU_addr_index.
   void addOpAddress(DIELoc &Die, const MCSymbol *Label);
 
-  /// addLabelDelta - Add a label delta attribute data and value.
+  /// \brief Add a label delta attribute data and value.
   void addLabelDelta(DIE &Die, dwarf::Attribute Attribute, const MCSymbol *Hi,
                      const MCSymbol *Lo);
 
-  /// addDIEEntry - Add a DIE attribute data and value.
+  /// \brief Add a DIE attribute data and value.
   void addDIEEntry(DIE &Die, dwarf::Attribute Attribute, DIE &Entry);
 
-  /// addDIEEntry - Add a DIE attribute data and value.
+  /// \brief Add a DIE attribute data and value.
   void addDIEEntry(DIE &Die, dwarf::Attribute Attribute, DIEEntry *Entry);
 
   void addDIETypeSignature(DIE &Die, const DwarfTypeUnit &Type);
 
-  /// addBlock - Add block data.
+  /// \brief Add block data.
   void addBlock(DIE &Die, dwarf::Attribute Attribute, DIELoc *Block);
 
-  /// addBlock - Add block data.
+  /// \brief Add block data.
   void addBlock(DIE &Die, dwarf::Attribute Attribute, DIEBlock *Block);
 
-  /// addSourceLine - Add location information to specified debug information
-  /// entry.
+  /// \brief Add location information to specified debug information entry.
   void addSourceLine(DIE &Die, unsigned Line, StringRef File,
                      StringRef Directory);
   void addSourceLine(DIE &Die, DIVariable V);
@@ -243,21 +253,21 @@ public:
   void addSourceLine(DIE &Die, DINameSpace NS);
   void addSourceLine(DIE &Die, DIObjCProperty Ty);
 
-  /// addConstantValue - Add constant value entry in variable DIE.
+  /// \brief Add constant value entry in variable DIE.
   void addConstantValue(DIE &Die, const MachineOperand &MO, const MDType *Ty);
   void addConstantValue(DIE &Die, const ConstantInt *CI, const MDType *Ty);
   void addConstantValue(DIE &Die, const APInt &Val, const MDType *Ty);
   void addConstantValue(DIE &Die, const APInt &Val, bool Unsigned);
   void addConstantValue(DIE &Die, bool Unsigned, uint64_t Val);
 
-  /// addConstantFPValue - Add constant value entry in variable DIE.
+  /// \brief Add constant value entry in variable DIE.
   void addConstantFPValue(DIE &Die, const MachineOperand &MO);
   void addConstantFPValue(DIE &Die, const ConstantFP *CFP);
 
   /// \brief Add a linkage name, if it isn't empty.
   void addLinkageName(DIE &Die, StringRef LinkageName);
 
-  /// addTemplateParams - Add template parameters in buffer.
+  /// \brief Add template parameters in buffer.
   void addTemplateParams(DIE &Buffer, DIArray TParams);
 
   /// \brief Add register operand.
@@ -272,45 +282,40 @@ public:
   bool addRegisterOffset(DIELoc &TheDie, unsigned Reg, int64_t Offset);
 
   // FIXME: Should be reformulated in terms of addComplexAddress.
-  /// addBlockByrefAddress - Start with the address based on the location
-  /// provided, and generate the DWARF information necessary to find the
-  /// actual Block variable (navigating the Block struct) based on the
-  /// starting location.  Add the DWARF information to the die.  Obsolete,
-  /// please use addComplexAddress instead.
+  /// Start with the address based on the location provided, and generate the
+  /// DWARF information necessary to find the actual Block variable (navigating
+  /// the Block struct) based on the starting location.  Add the DWARF
+  /// information to the die.  Obsolete, please use addComplexAddress instead.
   void addBlockByrefAddress(const DbgVariable &DV, DIE &Die,
                             dwarf::Attribute Attribute,
                             const MachineLocation &Location);
 
-  /// addType - Add a new type attribute to the specified entity. This takes
-  /// and attribute parameter because DW_AT_friend attributes are also
-  /// type references.
+  /// \brief Add a new type attribute to the specified entity.
+  ///
+  /// This takes and attribute parameter because DW_AT_friend attributes are
+  /// also type references.
   void addType(DIE &Entity, const MDType *Ty,
                dwarf::Attribute Attribute = dwarf::DW_AT_type);
 
-  /// getOrCreateNameSpace - Create a DIE for DINameSpace.
   DIE *getOrCreateNameSpace(DINameSpace NS);
-
-  /// getOrCreateSubprogramDIE - Create new DIE using SP.
   DIE *getOrCreateSubprogramDIE(DISubprogram SP, bool Minimal = false);
 
   void applySubprogramAttributes(DISubprogram SP, DIE &SPDie,
                                  bool Minimal = false);
 
-  /// getOrCreateTypeDIE - Find existing DIE or create new DIE for the
-  /// given type.
+  /// \brief Find existing DIE or create new DIE for the given type.
   DIE *getOrCreateTypeDIE(const MDNode *N);
 
-  /// getOrCreateContextDIE - Get context owner's DIE.
+  /// \brief Get context owner's DIE.
   DIE *createTypeDIE(DICompositeType Ty);
 
-  /// getOrCreateContextDIE - Get context owner's DIE.
+  /// \brief Get context owner's DIE.
   DIE *getOrCreateContextDIE(const MDScope *Context);
 
-  /// constructContainingTypeDIEs - Construct DIEs for types that contain
-  /// vtables.
+  /// \brief Construct DIEs for types that contain vtables.
   void constructContainingTypeDIEs();
 
-  /// constructSubprogramArguments - Construct function argument DIEs.
+  /// \brief Construct function argument DIEs.
   void constructSubprogramArguments(DIE &Buffer, DITypeArray Args);
 
   /// Create a DIE with the given Tag, add the DIE to its parent, and
@@ -330,76 +335,57 @@ public:
 
   virtual DwarfCompileUnit &getCU() = 0;
 
-  /// constructTypeDIE - Construct type DIE from DICompositeType.
   void constructTypeDIE(DIE &Buffer, DICompositeType CTy);
 
 protected:
-  /// getOrCreateStaticMemberDIE - Create new static data member DIE.
+  /// \brief Create new static data member DIE.
   DIE *getOrCreateStaticMemberDIE(DIDerivedType DT);
 
   /// Look up the source ID with the given directory and source file names. If
   /// none currently exists, create a new ID and insert it in the line table.
   virtual unsigned getOrCreateSourceID(StringRef File, StringRef Directory) = 0;
 
-  /// resolve - Look in the DwarfDebug map for the MDNode that
-  /// corresponds to the reference.
+  /// \brief Look in the DwarfDebug map for the MDNode that corresponds to the
+  /// reference.
   template <typename T> T *resolve(TypedDebugNodeRef<T> Ref) const {
     return DD->resolve(Ref);
   }
 
 private:
-  /// constructTypeDIE - Construct basic type die from DIBasicType.
   void constructTypeDIE(DIE &Buffer, DIBasicType BTy);
-
-  /// constructTypeDIE - Construct derived type die from DIDerivedType.
   void constructTypeDIE(DIE &Buffer, DIDerivedType DTy);
-
-  /// constructSubrangeDIE - Construct subrange DIE from DISubrange.
   void constructSubrangeDIE(DIE &Buffer, DISubrange SR, DIE *IndexTy);
-
-  /// constructArrayTypeDIE - Construct array type DIE from DICompositeType.
   void constructArrayTypeDIE(DIE &Buffer, DICompositeType CTy);
-
-  /// constructEnumTypeDIE - Construct enum type DIE from DIEnumerator.
   void constructEnumTypeDIE(DIE &Buffer, DICompositeType CTy);
-
-  /// constructMemberDIE - Construct member DIE from DIDerivedType.
   void constructMemberDIE(DIE &Buffer, DIDerivedType DT);
-
-  /// constructTemplateTypeParameterDIE - Construct new DIE for the given
-  /// DITemplateTypeParameter.
   void constructTemplateTypeParameterDIE(DIE &Buffer,
                                          DITemplateTypeParameter TP);
-
-  /// constructTemplateValueParameterDIE - Construct new DIE for the given
-  /// DITemplateValueParameter.
   void constructTemplateValueParameterDIE(DIE &Buffer,
                                           DITemplateValueParameter TVP);
 
-  /// getLowerBoundDefault - Return the default lower bound for an array. If the
-  /// DWARF version doesn't handle the language, return -1.
+  /// \brief Return the default lower bound for an array.
+  ///
+  /// If the DWARF version doesn't handle the language, return -1.
   int64_t getDefaultLowerBound() const;
 
-  /// getDIEEntry - Returns the debug information entry for the specified
-  /// debug variable.
+  /// \brief Returns the DIE entry for the specified debug variable.
   DIEEntry *getDIEEntry(const MDNode *N) const {
     return MDNodeToDIEEntryMap.lookup(N);
   }
 
-  /// insertDIEEntry - Insert debug information entry into the map.
+  /// \brief Insert debug information entry into the map.
   void insertDIEEntry(const MDNode *N, DIEEntry *E) {
     MDNodeToDIEEntryMap.insert(std::make_pair(N, E));
   }
 
-  // getIndexTyDie - Get an anonymous type for index type.
+  /// \brief Get an anonymous type for index type.
   DIE *getIndexTyDie();
 
-  // setIndexTyDie - Set D as anonymous type for index which can be reused
-  // later.
+  /// \brief Set D as anonymous type for index which can be reused later.
   void setIndexTyDie(DIE *D) { IndexTyDie = D; }
 
-  /// createDIEEntry - Creates a new DIEEntry to be a proxy for a debug
-  /// information entry.
+  /// \brief Creates a new DIEEntry to be a proxy for a debug information
+  /// entry.
   DIEEntry *createDIEEntry(DIE &Entry);
 
   /// If this is a named finished type then include it in the list of types for





More information about the llvm-commits mailing list