From 220b35542a69cce5a1ec6d0c5df3c0995b0b85c1 Mon Sep 17 00:00:00 2001 From: "Duncan P. N. Exon Smith" Date: Wed, 15 Oct 2014 17:01:28 +0000 Subject: [PATCH] DI: Make comments "brief"-er, NFC Follow-up to r219801. Post-commit review pointed out that all comments require a `\brief` description [1], so I converted many and recrafted a few to be briefer or to include a brief intro. (If I'm going to clean them up, I should do it right!) [1]: http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments llvm-svn: 219808 --- include/llvm/IR/DebugInfo.h | 178 ++++++++++++++++++++---------------- lib/IR/DebugInfo.cpp | 16 ++-- 2 files changed, 109 insertions(+), 85 deletions(-) diff --git a/include/llvm/IR/DebugInfo.h b/include/llvm/IR/DebugInfo.h index 016fc1ac0c5..63fbe60ded5 100644 --- a/include/llvm/IR/DebugInfo.h +++ b/include/llvm/IR/DebugInfo.h @@ -54,7 +54,7 @@ class DIType; class DIScope; class DIObjCProperty; -/// Maps from type identifier to the actual MDNode. +/// \brief Maps from type identifier to the actual MDNode. typedef DenseMap DITypeIdentifierMap; class DIHeaderFieldIterator @@ -106,17 +106,20 @@ private: } }; -/// A thin wraper around MDNode to access encoded debug info. This should not -/// be stored in a container, because the underlying MDNode may change in -/// certain situations. +/// \brief A thin wraper around MDNode to access encoded debug info. +/// +/// This should not be stored in a container, because the underlying MDNode may +/// change in certain situations. class DIDescriptor { // Befriends DIRef so DIRef can befriend the protected member // function: getFieldAs. template friend class DIRef; public: - /// The three accessibility flags are mutually exclusive and rolled - /// together in the first two bits. + /// \brief Accessibility flags. + /// + /// The three accessibility flags are mutually exclusive and rolled together + /// in the first two bits. enum { FlagAccessibility = 1 << 0 | 1 << 1, FlagPrivate = 1, @@ -229,12 +232,12 @@ public: void print(raw_ostream &OS) const; void dump() const; - /// Replace all uses of debug info referenced by this descriptor. + /// \brief Replace all uses of debug info referenced by this descriptor. void replaceAllUsesWith(LLVMContext &VMContext, DIDescriptor D); void replaceAllUsesWith(MDNode *D); }; -/// This is used to represent ranges, for array bounds. +/// \brief This is used to represent ranges, for array bounds. class DISubrange : public DIDescriptor { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -247,7 +250,7 @@ public: bool Verify() const; }; -/// This descriptor holds an array of nodes with type T. +/// \brief This descriptor holds an array of nodes with type T. template class DITypedArray : public DIDescriptor { public: explicit DITypedArray(const MDNode *N = nullptr) : DIDescriptor(N) {} @@ -261,7 +264,8 @@ public: typedef DITypedArray DIArray; -/// A wrapper for an enumerator (e.g. X and Y in 'enum {X,Y}'). +/// \brief A wrapper for an enumerator (e.g. X and Y in 'enum {X,Y}'). +/// /// FIXME: it seems strange that this doesn't have either a reference to the /// type/precision or a file/line pair for location info. class DIEnumerator : public DIDescriptor { @@ -281,7 +285,7 @@ typedef DIRef DIScopeRef; typedef DIRef DITypeRef; typedef DITypedArray DITypeArray; -/// A base class for various scopes. +/// \brief A base class for various scopes. /// /// Although, implementation-wise, DIScope is the parent class of most /// other DIxxx classes, including DIType and its descendants, most of @@ -297,21 +301,28 @@ protected: public: explicit DIScope(const MDNode *N = nullptr) : DIDescriptor(N) {} + /// \brief Get the parent scope. + /// /// Gets the parent scope for this scope node or returns a default /// constructed scope. DIScopeRef getContext() const; + /// \brief Get the scope name. + /// /// If the scope node has a name, return that, else return an empty string. StringRef getName() const; StringRef getFilename() const; StringRef getDirectory() const; - /// Generate a reference to this DIScope. Uses the type identifier instead - /// of the actual MDNode if possible, to help type uniquing. + /// \brief Generate a reference to this DIScope. + /// + /// Uses the type identifier instead of the actual MDNode if possible, to + /// help type uniquing. DIScopeRef getRef() const; }; -/// Represents reference to a DIDescriptor, abstracts over direct and -/// identifier-based metadata references. +/// \brief Represents reference to a DIDescriptor. +/// +/// Abstracts over direct and identifier-based metadata references. template class DIRef { template friend DescTy DIDescriptor::getFieldAs(unsigned Elt) const; @@ -319,8 +330,9 @@ template class DIRef { friend DIScopeRef DIScope::getRef() const; friend class DIType; - /// Val can be either a MDNode or a MDString, in the latter, - /// MDString specifies the type identifier. + /// \brief Val can be either a MDNode or a MDString. + /// + /// In the latter, MDString specifies the type identifier. const Value *Val; explicit DIRef(const Value *V); @@ -358,17 +370,18 @@ template StringRef DIRef::getName() const { return MS->getString(); } -/// Specialize getFieldAs to handle fields that are references to DIScopes. +/// \brief Handle fields that are references to DIScopes. template <> DIScopeRef DIDescriptor::getFieldAs(unsigned Elt) const; -/// Specialize DIRef constructor for DIScopeRef. +/// \brief Specialize DIRef constructor for DIScopeRef. template <> DIRef::DIRef(const Value *V); -/// Specialize getFieldAs to handle fields that are references to DITypes. +/// \brief Handle fields that are references to DITypes. template <> DITypeRef DIDescriptor::getFieldAs(unsigned Elt) const; -/// Specialize DIRef constructor for DITypeRef. +/// \brief Specialize DIRef constructor for DITypeRef. template <> DIRef::DIRef(const Value *V); -/// This is a wrapper for a type. +/// \briefThis is a wrapper for a type. +/// /// FIXME: Types should be factored much better so that CV qualifiers and /// others do not require a huge and empty descriptor full of zeros. class DIType : public DIScope { @@ -436,7 +449,7 @@ public: bool isValid() const { return DbgNode && isType(); } }; -/// A basic type, like 'int' or 'float'. +/// \brief A basic type, like 'int' or 'float'. class DIBasicType : public DIType { public: explicit DIBasicType(const MDNode *N = nullptr) : DIType(N) {} @@ -446,8 +459,10 @@ public: bool Verify() const; }; -/// A simple derived type, like a const qualified type, a typedef, a pointer or -/// reference, et cetera. Or, a data member of a class/struct/union. +/// \brief A simple derived type +/// +/// Like a const qualified type, a typedef, a pointer or reference, et cetera. +/// Or, a data member of a class/struct/union. class DIDerivedType : public DIType { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -457,7 +472,7 @@ public: DITypeRef getTypeDerivedFrom() const { return getFieldAs(3); } - /// Return property node, if this ivar is associated with one. + /// \brief Return property node, if this ivar is associated with one. MDNode *getObjCProperty() const; DITypeRef getClassType() const { @@ -473,6 +488,8 @@ public: bool Verify() const; }; +/// \brief Types that refer to multiple other types. +/// /// This descriptor holds a type that can refer to multiple other types, like a /// function or struct. /// @@ -522,7 +539,7 @@ public: } }; -/// This is a wrapper for a file. +/// \brief This is a wrapper for a file. class DIFile : public DIScope { friend class DIDescriptor; @@ -534,7 +551,7 @@ public: bool Verify() const; }; -/// A wrapper for a compile unit. +/// \brief A wrapper for a compile unit. class DICompileUnit : public DIScope { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -566,7 +583,7 @@ public: bool Verify() const; }; -/// This is a wrapper for a subprogram (e.g. a function). +/// \brief This is a wrapper for a subprogram (e.g. a function). class DISubprogram : public DIScope { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -579,8 +596,7 @@ public: StringRef getLinkageName() const { return getHeaderField(3); } unsigned getLineNumber() const { return getHeaderFieldAs(4); } - /// Return true if this subprogram is local to the current compile unit, like - /// 'static' in C. + /// \brief Check if this is local (like 'static' in C). unsigned isLocalToUnit() const { return getHeaderFieldAs(5); } unsigned isDefinition() const { return getHeaderFieldAs(6); } @@ -591,8 +607,7 @@ public: unsigned isOptimized() const { return getHeaderFieldAs(10); } - /// Get the beginning of the scope of the function, not necessarily where the - /// name of the program starts. + /// \brief Get the beginning of the scope of the function (not the name). unsigned getScopeLineNumber() const { return getHeaderFieldAs(11); } DIScopeRef getContext() const { return getFieldAs(2); } @@ -602,8 +617,7 @@ public: bool Verify() const; - /// Return true if this subprogram provides debugging information for the - /// function F. + /// \brief Check if this provides debugging information for the function F. bool describes(const Function *F); Function *getFunction() const { return getFunctionField(5); } @@ -616,29 +630,33 @@ public: DIArray getVariables() const; unsigned isArtificial() const { return (getFlags() & FlagArtificial) != 0; } - /// Return true if this subprogram has "private" access specifier. + /// \brief Check for the "private" access specifier. bool isPrivate() const { return (getFlags() & FlagAccessibility) == FlagPrivate; } - /// Return true if this subprogram has "protected" access specifier. + /// \brief Check for the "protected" access specifier. bool isProtected() const { return (getFlags() & FlagAccessibility) == FlagProtected; } - /// Return true if this subprogram has "public" access specifier. + /// \brief Check for the "public" access specifier. bool isPublic() const { return (getFlags() & FlagAccessibility) == FlagPublic; } - /// Return true if this subprogram is marked as explicit. + /// \brief Check for "explicit". bool isExplicit() const { return (getFlags() & FlagExplicit) != 0; } - /// Return true if this subprogram is prototyped. + /// \brief Check if this is prototyped. bool isPrototyped() const { return (getFlags() & FlagPrototyped) != 0; } + /// \brief Check if this is reference-qualified. + /// /// Return true if this subprogram is a C++11 reference-qualified non-static /// member function (void foo() &). unsigned isLValueReference() const { return (getFlags() & FlagLValueReference) != 0; } + /// \brief Check if this is rvalue-reference-qualified. + /// /// Return true if this subprogram is a C++11 rvalue-reference-qualified /// non-static member function (void foo() &&). unsigned isRValueReference() const { @@ -647,7 +665,7 @@ public: }; -/// This is a wrapper for a lexical block. +/// \brief This is a wrapper for a lexical block. class DILexicalBlock : public DIScope { public: explicit DILexicalBlock(const MDNode *N = nullptr) : DIScope(N) {} @@ -661,7 +679,7 @@ public: bool Verify() const; }; -/// This is a wrapper for a lexical block with a filename change. +/// \brief This is a wrapper for a lexical block with a filename change. class DILexicalBlockFile : public DIScope { public: explicit DILexicalBlockFile(const MDNode *N = nullptr) : DIScope(N) {} @@ -677,7 +695,7 @@ public: bool Verify() const; }; -/// A wrapper for a C++ style name space. +/// \brief A wrapper for a C++ style name space. class DINameSpace : public DIScope { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -690,7 +708,7 @@ public: bool Verify() const; }; -/// This is a wrapper for template type parameter. +/// \brief This is a wrapper for template type parameter. class DITemplateTypeParameter : public DIDescriptor { public: explicit DITemplateTypeParameter(const MDNode *N = nullptr) @@ -709,7 +727,7 @@ public: bool Verify() const; }; -/// This is a wrapper for template value parameter. +/// \brief This is a wrapper for template value parameter. class DITemplateValueParameter : public DIDescriptor { public: explicit DITemplateValueParameter(const MDNode *N = nullptr) @@ -729,7 +747,7 @@ public: bool Verify() const; }; -/// This is a wrapper for a global variable. +/// \brief This is a wrapper for a global variable. class DIGlobalVariable : public DIDescriptor { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -760,7 +778,7 @@ public: bool Verify() const; }; -/// This is a wrapper for a variable (e.g. parameter, local, global etc). +/// \brief This is a wrapper for a variable (e.g. parameter, local, global etc). class DIVariable : public DIDescriptor { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -779,7 +797,7 @@ public: DIFile getFile() const { return getFieldAs(2); } DITypeRef getType() const { return getFieldAs(3); } - /// Return true if this variable is marked as "artificial". + /// \brief Return true if this variable is marked as "artificial". bool isArtificial() const { return (getHeaderFieldAs(3) & FlagArtificial) != 0; } @@ -793,28 +811,26 @@ public: return (getHeaderFieldAs(3) & FlagIndirectVariable) != 0; } - /// If this variable is inlined then return inline location. + /// \brief If this variable is inlined then return inline location. MDNode *getInlinedAt() const; bool Verify() const; - /// Return true if the variable was declared as a "__block" variable (Apple - /// Blocks). + /// \brief Check if this is a "__block" variable (Apple Blocks). bool isBlockByrefVariable(const DITypeIdentifierMap &Map) const { return (getType().resolve(Map)).isBlockByrefStruct(); } - /// Return true if this variable provides debugging information for an - /// inlined function arguments. + /// \brief Check if this is an inlined function argument. bool isInlinedFnArgument(const Function *CurFn); - /// Return the size reported by the variable's type. + /// \brief Return the size reported by the variable's type. unsigned getSizeInBits(const DITypeIdentifierMap &Map); void printExtendedName(raw_ostream &OS) const; }; -/// A complex location expression. +/// \brief A complex location expression. class DIExpression : public DIDescriptor { friend class DIDescriptor; void printInternal(raw_ostream &OS) const; @@ -836,16 +852,17 @@ public: /// \brief return the Idx'th complex address element. uint64_t getElement(unsigned Idx) const; - /// Return whether this is a piece of an aggregate variable. + /// \brief Return whether this is a piece of an aggregate variable. bool isVariablePiece() const; - /// Return the offset of this piece in bytes. + /// \brief Return the offset of this piece in bytes. uint64_t getPieceOffset() const; - /// Return the size of this piece in bytes. + /// \brief Return the size of this piece in bytes. uint64_t getPieceSize() const; }; -/// This object holds location information. This object is not associated with -/// any DWARF tag. +/// \brief This object holds location information. +/// +/// This object is not associated with any DWARF tag. class DILocation : public DIDescriptor { public: explicit DILocation(const MDNode *N) : DIDescriptor(N) {} @@ -861,6 +878,8 @@ public: return (getLineNumber() == Other.getLineNumber() && getFilename() == Other.getFilename()); } + /// \brief Get the DWAF discriminator. + /// /// DWARF discriminators are used to distinguish identical file locations for /// instructions that are on different basic blocks. If two instructions are /// inside the same lexical block and are in different basic blocks, we @@ -876,11 +895,10 @@ public: : 0; } - /// Generate a new discriminator value for this file and line location. + /// \brief Generate a new discriminator value for this location. unsigned computeNewDiscriminator(LLVMContext &Ctx); - /// Return a copy of this location, replacing the current scope with the - /// given one. + /// \brief Return a copy of this location with a different scope. DILocation copyWithNewScope(LLVMContext &Ctx, DILexicalBlockFile NewScope); }; @@ -917,7 +935,9 @@ public: return (getAttributes() & dwarf::DW_APPLE_PROPERTY_nonatomic) != 0; } - /// Objective-C doesn't have an ODR, so there is no benefit in storing + /// \brief Get the type. + /// + /// \note Objective-C doesn't have an ODR, so there is no benefit in storing /// the type as a DITypeRef here. DIType getType() const { return getFieldAs(2); } @@ -938,34 +958,37 @@ public: bool Verify() const; }; -/// Find subprogram that is enclosing this scope. +/// \brief Find subprogram that is enclosing this scope. DISubprogram getDISubprogram(const MDNode *Scope); -/// Find underlying composite type. +/// \brief Find underlying composite type. DICompositeType getDICompositeType(DIType T); -/// Create a new inlined variable based on current variable. +/// \brief Create a new inlined variable based on current variable. +/// /// @param DV Current Variable. /// @param InlinedScope Location at current variable is inlined. DIVariable createInlinedVariable(MDNode *DV, MDNode *InlinedScope, LLVMContext &VMContext); -/// Remove inlined scope from the variable. +/// \brief Remove inlined scope from the variable. DIVariable cleanseInlinedVariable(MDNode *DV, LLVMContext &VMContext); -/// Construct DITypeIdentifierMap by going through retained types of each CU. +/// \brief Generate map by visiting all retained types. DITypeIdentifierMap generateDITypeIdentifierMap(const NamedMDNode *CU_Nodes); -/// Strip debug info in the module if it exists. +/// \brief Strip debug info in the module if it exists. /// /// To do this, we remove all calls to the debugger intrinsics and any named /// metadata for debugging. We also remove debug locations for instructions. /// Return true if module is modified. bool StripDebugInfo(Module &M); -/// Return Debug Info Metadata Version by checking module flags. +/// \brief Return Debug Info Metadata Version by checking module flags. unsigned getDebugMetadataVersionFromModule(const Module &M); +/// \brief Utility to find all debug info in a module. +/// /// DebugInfoFinder tries to list all debug info MDNodes used in a module. To /// list debug info MDNodes used by an instruction, DebugInfoFinder uses /// processDeclare, processValue and processLocation to handle DbgDeclareInst, @@ -976,17 +999,17 @@ class DebugInfoFinder { public: DebugInfoFinder() : TypeMapInitialized(false) {} - /// Process entire module and collect debug info anchors. + /// \brief Process entire module and collect debug info anchors. void processModule(const Module &M); - /// Process DbgDeclareInst. + /// \brief Process DbgDeclareInst. void processDeclare(const Module &M, const DbgDeclareInst *DDI); - /// Process DbgValueInst. + /// \brief Process DbgValueInst. void processValue(const Module &M, const DbgValueInst *DVI); - /// Process DILocation. + /// \brief Process DILocation. void processLocation(const Module &M, DILocation Loc); - /// Clear all lists. + /// \brief Clear all lists. void reset(); private: @@ -1042,7 +1065,8 @@ private: SmallVector Scopes; SmallPtrSet NodesSeen; DITypeIdentifierMap TypeIdentifierMap; - /// Specify if TypeIdentifierMap is initialized. + + /// \brief Specify if TypeIdentifierMap is initialized. bool TypeMapInitialized; }; diff --git a/lib/IR/DebugInfo.cpp b/lib/IR/DebugInfo.cpp index 054e3d0dbb0..04eb65bc2a7 100644 --- a/lib/IR/DebugInfo.cpp +++ b/lib/IR/DebugInfo.cpp @@ -143,7 +143,7 @@ MDNode *DIVariable::getInlinedAt() const { return getNodeField(DbgNode, DIVariableInlinedAtIndex); } -/// Return the size reported by the variable's type. +/// \brief Return the size reported by the variable's type. unsigned DIVariable::getSizeInBits(const DITypeIdentifierMap &Map) { DIType Ty = getType().resolve(Map); // Follow derived types until we reach a type that @@ -391,7 +391,8 @@ bool DIObjCProperty::Verify() const { return DbgNode->getNumOperands() == 3 && getNumHeaderFields() == 6; } -/// Check if a field at position Elt of a MDNode is a MDNode. +/// \brief Check if a field at position Elt of a MDNode is a MDNode. +/// /// We currently allow an empty string and an integer. /// But we don't allow a non-empty string in a MDNode field. static bool fieldIsMDNode(const MDNode *DbgNode, unsigned Elt) { @@ -403,26 +404,26 @@ static bool fieldIsMDNode(const MDNode *DbgNode, unsigned Elt) { return true; } -/// Check if a field at position Elt of a MDNode is a MDString. +/// \brief Check if a field at position Elt of a MDNode is a MDString. static bool fieldIsMDString(const MDNode *DbgNode, unsigned Elt) { Value *Fld = getField(DbgNode, Elt); return !Fld || isa(Fld); } -/// Check if a value can be a reference to a type. +/// \brief Check if a value can be a reference to a type. static bool isTypeRef(const Value *Val) { return !Val || (isa(Val) && !cast(Val)->getString().empty()) || (isa(Val) && DIType(cast(Val)).isType()); } -/// Check if a field at position Elt of a MDNode can be a reference to a type. +/// \brief Check if referenced field might be a type. static bool fieldIsTypeRef(const MDNode *DbgNode, unsigned Elt) { Value *Fld = getField(DbgNode, Elt); return isTypeRef(Fld); } -/// Check if a value can be a ScopeRef. +/// \brief Check if a value can be a ScopeRef. static bool isScopeRef(const Value *Val) { return !Val || (isa(Val) && !cast(Val)->getString().empty()) || @@ -431,7 +432,7 @@ static bool isScopeRef(const Value *Val) { isa(Val); } -/// Check if a field at position Elt of a MDNode can be a ScopeRef. +/// \brief Check if a field at position Elt of a MDNode can be a ScopeRef. static bool fieldIsScopeRef(const MDNode *DbgNode, unsigned Elt) { Value *Fld = getField(DbgNode, Elt); return isScopeRef(Fld); @@ -470,7 +471,6 @@ bool DIType::Verify() const { return false; } -/// Verify - Verify that a basic type descriptor is well formed. bool DIBasicType::Verify() const { return isBasicType() && DbgNode->getNumOperands() == 3 && getNumHeaderFields() == 8;