Clean up the comments and doxygen for DataLayout.

llvm-svn: 220191

llvm/include/llvm/IR/DataLayout.h

@@ -27,7 +27,8 @@
 #include "llvm/Pass.h"
 #include "llvm/Support/DataTypes.h"
 
-// this needs to be outside of the namespace, to avoid conflict with llvm-c decl
+// This needs to be outside of the namespace, to avoid conflict with llvm-c
+// decl.
 typedef struct LLVMOpaqueTargetData *LLVMTargetDataRef;
 
 namespace llvm {
@@ -52,12 +53,12 @@ enum AlignTypeEnum {
   AGGREGATE_ALIGN = 'a'              ///< Aggregate alignment
 };
 
-/// Layout alignment element.
+/// \brief Layout alignment element.
 ///
 /// Stores the alignment data associated with a given alignment type (integer,
 /// vector, float) and type bit width.
 ///
-/// @note The unusual order of elements in the structure attempts to reduce
+/// \note The unusual order of elements in the structure attempts to reduce
 /// padding and make the structure slightly more cache friendly.
 struct LayoutAlignElem {
   unsigned AlignType    : 8;  ///< Alignment type (AlignTypeEnum)
@@ -65,18 +66,16 @@ struct LayoutAlignElem {
   unsigned ABIAlign     : 16; ///< ABI alignment for this type/bitw
   unsigned PrefAlign    : 16; ///< Pref. alignment for this type/bitw
 
-  /// Initializer
   static LayoutAlignElem get(AlignTypeEnum align_type, unsigned abi_align,
                              unsigned pref_align, uint32_t bit_width);
-  /// Equality predicate
   bool operator==(const LayoutAlignElem &rhs) const;
 };
 
-/// Layout pointer alignment element.
+/// \brief Layout pointer alignment element.
 ///
 /// Stores the alignment data associated with a given pointer and address space.
 ///
-/// @note The unusual order of elements in the structure attempts to reduce
+/// \note The unusual order of elements in the structure attempts to reduce
 /// padding and make the structure slightly more cache friendly.
 struct PointerAlignElem {
   unsigned            ABIAlign;       ///< ABI alignment for this type/bitw
@@ -87,18 +86,21 @@ struct PointerAlignElem {
   /// Initializer
   static PointerAlignElem get(uint32_t AddressSpace, unsigned ABIAlign,
                              unsigned PrefAlign, uint32_t TypeByteWidth);
-  /// Equality predicate
   bool operator==(const PointerAlignElem &rhs) const;
 };
 
-/// This class holds a parsed version of the target data layout string in a
+/// \brief A parsed version of the target data layout string in and methods for
-/// module and provides methods for querying it. The target data layout string
+/// querying it.
-/// is specified *by the target* - a frontend generating LLVM IR is required to
+///
-/// generate the right target data for the target being codegen'd to.
+/// The target data layout string is specified *by the target* - a frontend
+/// generating LLVM IR is required to generate the right target data for the
+/// target being codegen'd to.
 class DataLayout {
 private:
-  bool          LittleEndian;          ///< Defaults to false
+  /// Defaults to false.
-  unsigned      StackNaturalAlign;     ///< Stack natural alignment
+  bool          LittleEndian;
+
+  unsigned      StackNaturalAlign;
 
   enum ManglingModeT {
     MM_None,
@@ -109,15 +111,11 @@ private:
   };
   ManglingModeT ManglingMode;
 
-  SmallVector<unsigned char, 8> LegalIntWidths; ///< Legal Integers.
+  SmallVector<unsigned char, 8> LegalIntWidths;
 
-  /// Alignments - Where the primitive type alignment data is stored.
+  /// \brief Primitive type alignment data.
-  ///
-  /// @sa reset().
-  /// @note Could support multiple size pointer alignments, e.g., 32-bit
-  /// pointers vs. 64-bit pointers by extending LayoutAlignment, but for now,
-  /// we don't.
   SmallVector<LayoutAlignElem, 16> Alignments;
+
   typedef SmallVector<PointerAlignElem, 8> PointersTy;
   PointersTy Pointers;
 
@@ -128,31 +126,28 @@ private:
 
   PointersTy::iterator findPointerLowerBound(uint32_t AddressSpace);
 
-  /// InvalidAlignmentElem - This member is a signal that a requested alignment
+  /// This member is a signal that a requested alignment type and bit width were
-  /// type and bit width were not found in the SmallVector.
+  /// not found in the SmallVector.
   static const LayoutAlignElem InvalidAlignmentElem;
 
-  /// InvalidPointerElem - This member is a signal that a requested pointer
+  /// This member is a signal that a requested pointer type and bit width were
-  /// type and bit width were not found in the DenseSet.
+  /// not found in the DenseSet.
   static const PointerAlignElem InvalidPointerElem;
 
   // The StructType -> StructLayout map.
   mutable void *LayoutMap;
 
-  //! Set/initialize target alignments
   void setAlignment(AlignTypeEnum align_type, unsigned abi_align,
                     unsigned pref_align, uint32_t bit_width);
   unsigned getAlignmentInfo(AlignTypeEnum align_type, uint32_t bit_width,
                             bool ABIAlign, Type *Ty) const;
-
-  //! Set/initialize pointer alignments
   void setPointerAlignment(uint32_t AddrSpace, unsigned ABIAlign,
                            unsigned PrefAlign, uint32_t TypeByteWidth);
 
-  //! Internal helper method that returns requested alignment for type.
+  /// Internal helper method that returns requested alignment for type.
   unsigned getAlignment(Type *Ty, bool abi_or_pref) const;
 
-  /// Valid alignment predicate.
+  /// \brief Valid alignment predicate.
   ///
   /// Predicate that tests a LayoutAlignElem reference returned by get() against
   /// InvalidAlignmentElem.
@@ -160,7 +155,7 @@ private:
     return &align != &InvalidAlignmentElem;
   }
 
-  /// Valid pointer predicate.
+  /// \brief Valid pointer predicate.
   ///
   /// Predicate that tests a PointerAlignElem reference returned by get() against
   /// InvalidPointerElem.
@@ -211,18 +206,19 @@ public:
   bool isLittleEndian() const { return LittleEndian; }
   bool isBigEndian() const { return !LittleEndian; }
 
-  /// getStringRepresentation - Return the string representation of the
+  /// \brief Returns the string representation of the DataLayout.
-  /// DataLayout.  This representation is in the same format accepted by the
+  ///
-  /// string constructor above.
+  /// This representation is in the same format accepted by the string
+  /// constructor above.
   std::string getStringRepresentation() const;
 
-  /// isLegalInteger - This function returns true if the specified type is
+  /// \brief Returns true if the specified type is known to be a native integer
-  /// known to be a native integer type supported by the CPU.  For example,
+  /// type supported by the CPU.
-  /// i64 is not native on most 32-bit CPUs and i37 is not native on any known
+  ///
-  /// one.  This returns false if the integer width is not legal.
+  /// For example, i64 is not native on most 32-bit CPUs and i37 is not native
+  /// on any known one. This returns false if the integer width is not legal.
   ///
   /// The width is specified in bits.
-  ///
   bool isLegalInteger(unsigned Width) const {
     for (unsigned LegalIntWidth : LegalIntWidths)
       if (LegalIntWidth == Width)
@@ -283,10 +279,11 @@ public:
 
   static const char *getManglingComponent(const Triple &T);
 
-  /// fitsInLegalInteger - This function returns true if the specified type fits
+  /// \brief Returns true if the specified type fits in a native integer type
-  /// in a native integer type supported by the CPU.  For example, if the CPU
+  /// supported by the CPU.
-  /// only supports i32 as a native integer type, then i27 fits in a legal
+  ///
-  /// integer type but i45 does not.
+  /// For example, if the CPU only supports i32 as a native integer type, then
+  /// i27 fits in a legal integer type but i45 does not.
   bool fitsInLegalInteger(unsigned Width) const {
     for (unsigned LegalIntWidth : LegalIntWidths)
       if (Width <= LegalIntWidth)
@@ -344,99 +341,107 @@ public:
   /// [*] The alloc size depends on the alignment, and thus on the target.
   ///     These values are for x86-32 linux.
 
-  /// getTypeSizeInBits - Return the number of bits necessary to hold the
+  /// \brief Returns the number of bits necessary to hold the specified type.
-  /// specified type.  For example, returns 36 for i36 and 80 for x86_fp80.
+  ///
-  /// The type passed must have a size (Type::isSized() must return true).
+  /// For example, returns 36 for i36 and 80 for x86_fp80. The type passed must
+  /// have a size (Type::isSized() must return true).
   uint64_t getTypeSizeInBits(Type *Ty) const;
 
-  /// getTypeStoreSize - Return the maximum number of bytes that may be
+  /// \brief Returns the maximum number of bytes that may be overwritten by
-  /// overwritten by storing the specified type.  For example, returns 5
+  /// storing the specified type.
-  /// for i36 and 10 for x86_fp80.
+  ///
+  /// For example, returns 5 for i36 and 10 for x86_fp80.
   uint64_t getTypeStoreSize(Type *Ty) const {
     return (getTypeSizeInBits(Ty)+7)/8;
   }
 
-  /// getTypeStoreSizeInBits - Return the maximum number of bits that may be
+  /// \brief Returns the maximum number of bits that may be overwritten by
-  /// overwritten by storing the specified type; always a multiple of 8.  For
+  /// storing the specified type; always a multiple of 8.
-  /// example, returns 40 for i36 and 80 for x86_fp80.
+  ///
+  /// For example, returns 40 for i36 and 80 for x86_fp80.
   uint64_t getTypeStoreSizeInBits(Type *Ty) const {
     return 8*getTypeStoreSize(Ty);
   }
 
-  /// getTypeAllocSize - Return the offset in bytes between successive objects
+  /// \brief Returns the offset in bytes between successive objects of the
-  /// of the specified type, including alignment padding.  This is the amount
+  /// specified type, including alignment padding.
-  /// that alloca reserves for this type.  For example, returns 12 or 16 for
+  ///
-  /// x86_fp80, depending on alignment.
+  /// This is the amount that alloca reserves for this type. For example,
+  /// returns 12 or 16 for x86_fp80, depending on alignment.
   uint64_t getTypeAllocSize(Type *Ty) const {
     // Round up to the next alignment boundary.
     return RoundUpToAlignment(getTypeStoreSize(Ty), getABITypeAlignment(Ty));
   }
 
-  /// getTypeAllocSizeInBits - Return the offset in bits between successive
+  /// \brief Returns the offset in bits between successive objects of the
-  /// objects of the specified type, including alignment padding; always a
+  /// specified type, including alignment padding; always a multiple of 8.
-  /// multiple of 8.  This is the amount that alloca reserves for this type.
+  ///
-  /// For example, returns 96 or 128 for x86_fp80, depending on alignment.
+  /// This is the amount that alloca reserves for this type. For example,
+  /// returns 96 or 128 for x86_fp80, depending on alignment.
   uint64_t getTypeAllocSizeInBits(Type *Ty) const {
     return 8*getTypeAllocSize(Ty);
   }
 
-  /// getABITypeAlignment - Return the minimum ABI-required alignment for the
+  /// \brief Returns the minimum ABI-required alignment for the specified type.
-  /// specified type.
   unsigned getABITypeAlignment(Type *Ty) const;
 
-  /// getABIIntegerTypeAlignment - Return the minimum ABI-required alignment for
+  /// \brief Returns the minimum ABI-required alignment for an integer type of
-  /// an integer type of the specified bitwidth.
+  /// the specified bitwidth.
   unsigned getABIIntegerTypeAlignment(unsigned BitWidth) const;
 
-  /// getPrefTypeAlignment - Return the preferred stack/global alignment for
+  /// \brief Returns the preferred stack/global alignment for the specified
-  /// the specified type.  This is always at least as good as the ABI alignment.
+  /// type.
+  ///
+  /// This is always at least as good as the ABI alignment.
   unsigned getPrefTypeAlignment(Type *Ty) const;
 
-  /// getPreferredTypeAlignmentShift - Return the preferred alignment for the
+  /// \brief Returns the preferred alignment for the specified type, returned as
-  /// specified type, returned as log2 of the value (a shift amount).
+  /// log2 of the value (a shift amount).
   unsigned getPreferredTypeAlignmentShift(Type *Ty) const;
 
-  /// getIntPtrType - Return an integer type with size at least as big as that
+  /// \brief Returns an integer type with size at least as big as that of a
-  /// of a pointer in the given address space.
+  /// pointer in the given address space.
   IntegerType *getIntPtrType(LLVMContext &C, unsigned AddressSpace = 0) const;
 
-  /// getIntPtrType - Return an integer (vector of integer) type with size at
+  /// \brief Returns an integer (vector of integer) type with size at least as
-  /// least as big as that of a pointer of the given pointer (vector of pointer)
+  /// big as that of a pointer of the given pointer (vector of pointer) type.
-  /// type.
   Type *getIntPtrType(Type *) const;
 
-  /// getSmallestLegalIntType - Return the smallest integer type with size at
+  /// \brief Returns the smallest integer type with size at least as big as
-  /// least as big as Width bits.
+  /// Width bits.
   Type *getSmallestLegalIntType(LLVMContext &C, unsigned Width = 0) const;
 
-  /// getLargestLegalIntType - Return the largest legal integer type, or null if
+  /// \brief Returns the largest legal integer type, or null if none are set.
-  /// none are set.
   Type *getLargestLegalIntType(LLVMContext &C) const {
     unsigned LargestSize = getLargestLegalIntTypeSize();
     return (LargestSize == 0) ? nullptr : Type::getIntNTy(C, LargestSize);
   }
 
-  /// getLargestLegalIntTypeSize - Return the size of largest legal integer
+  /// \brief Returns the size of largest legal integer type size, or 0 if none
-  /// type size, or 0 if none are set.
+  /// are set.
   unsigned getLargestLegalIntTypeSize() const;
 
-  /// getIndexedOffset - return the offset from the beginning of the type for
+  /// \brief Returns the offset from the beginning of the type for the specified
-  /// the specified indices.  This is used to implement getelementptr.
+  /// indices.
+  ///
+  /// This is used to implement getelementptr.
   uint64_t getIndexedOffset(Type *Ty, ArrayRef<Value *> Indices) const;
 
-  /// getStructLayout - Return a StructLayout object, indicating the alignment
+  /// \brief Returns a StructLayout object, indicating the alignment of the
-  /// of the struct, its size, and the offsets of its fields.  Note that this
+  /// struct, its size, and the offsets of its fields.
-  /// information is lazily cached.
+  ///
+  /// Note that this information is lazily cached.
   const StructLayout *getStructLayout(StructType *Ty) const;
 
-  /// getPreferredAlignment - Return the preferred alignment of the specified
+  /// \brief Returns the preferred alignment of the specified global.
-  /// global.  This includes an explicitly requested alignment (if the global
+  /// 
-  /// has one).
+  /// This includes an explicitly requested alignment (if the global has one).
   unsigned getPreferredAlignment(const GlobalVariable *GV) const;
 
-  /// getPreferredAlignmentLog - Return the preferred alignment of the
+  /// \brief Returns the preferred alignment of the specified global, returned
-  /// specified global, returned in log form.  This includes an explicitly
+  /// in log form.
-  /// requested alignment (if the global has one).
+  ///
+  /// This includes an explicitly requested alignment (if the global has one).
   unsigned getPreferredAlignmentLog(const GlobalVariable *GV) const;
 };
 
@@ -464,9 +469,8 @@ public:
   bool doInitialization(Module &M) override;
 };
 
-/// StructLayout - used to lazily calculate structure layout information for a
+/// Used to lazily calculate structure layout information for a target machine,
-/// target machine, based on the DataLayout structure.
+/// based on the DataLayout structure.
-///
 class StructLayout {
   uint64_t StructSize;
   unsigned StructAlignment;
@@ -486,9 +490,8 @@ public:
     return StructAlignment;
   }
 
-  /// getElementContainingOffset - Given a valid byte offset into the structure,
+  /// \brief Given a valid byte offset into the structure, returns the structure
-  /// return the structure index that contains it.
+  /// index that contains it.
-  ///
   unsigned getElementContainingOffset(uint64_t Offset) const;
 
   uint64_t getElementOffset(unsigned Idx) const {