[LLVM][Alignment] Update documentation

Reviewers: aprantl

Subscribers: llvm-commits

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D65558

llvm-svn: 367655

llvm/include/llvm/Support/Alignment.h

@@ -34,13 +34,13 @@ namespace llvm {
 #define ALIGN_CHECK_ISSET(decl)                                                \
   assert(decl.hasValue() && (#decl " should be defined"))
 
-// This struct is a compact representation of a valid (non-zero power of two)
+/// This struct is a compact representation of a valid (non-zero power of two)
-// alignment.
+/// alignment.
-// It is suitable for use as static global constants.
+/// It is suitable for use as static global constants.
 struct Align {
 private:
-  uint8_t ShiftValue = 0; // The log2 of the required alignment.
+  uint8_t ShiftValue = 0; /// The log2 of the required alignment.
-                          // ShiftValue is less than 64 by construction.
+                          /// ShiftValue is less than 64 by construction.
 
   friend struct MaybeAlign;
   friend unsigned Log2(Align);
@@ -54,10 +54,10 @@ private:
   friend struct MaybeAlign decodeMaybeAlign(unsigned Value);
 
 public:
-  // Default is byte-aligned.
+  /// Default is byte-aligned.
   Align() = default;
-  // Do not perform checks in case of copy/move construct/assign, because the
+  /// Do not perform checks in case of copy/move construct/assign, because the
-  // checks have been performed when building `Other`.
+  /// checks have been performed when building `Other`.
   Align(const Align &Other) = default;
   Align &operator=(const Align &Other) = default;
   Align(Align &&Other) = default;
@@ -70,33 +70,33 @@ public:
     assert(ShiftValue < 64 && "Broken invariant");
   }
 
-  // This is a hole in the type system and should not be abused.
+  /// This is a hole in the type system and should not be abused.
-  // Needed to interact with C for instance.
+  /// Needed to interact with C for instance.
   uint64_t value() const { return uint64_t(1) << ShiftValue; }
 };
 
-// Treats the value 0 as a 1, so Align is always at least 1.
+/// Treats the value 0 as a 1, so Align is always at least 1.
 inline Align assumeAligned(uint64_t Value) {
   return Value ? Align(Value) : Align();
 }
 
-// This struct is a compact representation of a valid (power of two) or
+/// This struct is a compact representation of a valid (power of two) or
-// undefined (0) alignment.
+/// undefined (0) alignment.
 struct MaybeAlign : public llvm::Optional<Align> {
 private:
   using UP = llvm::Optional<Align>;
 
 public:
-  // Default is undefined.
+  /// Default is undefined.
   MaybeAlign() = default;
-  // Do not perform checks in case of copy/move construct/assign, because the
+  /// Do not perform checks in case of copy/move construct/assign, because the
-  // checks have been performed when building `Other`.
+  /// checks have been performed when building `Other`.
   MaybeAlign(const MaybeAlign &Other) = default;
   MaybeAlign &operator=(const MaybeAlign &Other) = default;
   MaybeAlign(MaybeAlign &&Other) = default;
   MaybeAlign &operator=(MaybeAlign &&Other) = default;
 
-  // Use llvm::Optional<Align> constructor.
+  /// Use llvm::Optional<Align> constructor.
   using UP::UP;
 
   explicit MaybeAlign(uint64_t Value) {
@@ -106,78 +106,69 @@ public:
       emplace(Value);
   }
 
-  // For convenience, returns a valid alignment or 1 if undefined.
+  /// For convenience, returns a valid alignment or 1 if undefined.
   Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
 };
 
-// -----------------------------------------------------------------------------
+/// Checks that SizeInBytes is a multiple of the alignment.
-// isAligned: Checks that SizeInBytes is a multiple of the alignment.
-// -----------------------------------------------------------------------------
-
 inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
   return SizeInBytes % Lhs.value() == 0;
 }
 
-// Returns false if the alignment is undefined.
+/// Checks that SizeInBytes is a multiple of the alignment.
+/// Returns false if the alignment is undefined.
 inline bool isAligned(MaybeAlign Lhs, uint64_t SizeInBytes) {
   ALIGN_CHECK_ISSET(Lhs);
   return SizeInBytes % (*Lhs).value() == 0;
 }
 
-// -----------------------------------------------------------------------------
+/// Returns a multiple of A needed to store `Size` bytes.
-// alignTo: Returns a multiple of A needed to store `Size` bytes.
-// -----------------------------------------------------------------------------
-
 inline uint64_t alignTo(uint64_t Size, Align A) {
   return (Size + A.value() - 1) / A.value() * A.value();
 }
 
-// Returns `Size` if current alignment is undefined.
+/// Returns a multiple of A needed to store `Size` bytes.
+/// Returns `Size` if current alignment is undefined.
 inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
   return A ? alignTo(Size, A.getValue()) : Size;
 }
 
-// -----------------------------------------------------------------------------
+/// Returns the log2 of the alignment.
-// log2: Returns the log2 of the alignment.
-// e.g. Align(16).log2() == 4
-// -----------------------------------------------------------------------------
-
 inline unsigned Log2(Align A) { return A.ShiftValue; }
 
+/// Returns the log2 of the alignment.
 /// \pre A must be defined.
 inline unsigned Log2(MaybeAlign A) {
   ALIGN_CHECK_ISSET(A);
   return Log2(A.getValue());
 }
 
-// -----------------------------------------------------------------------------
+/// Returns the alignment that satisfies both alignments.
-// commonAlignment: returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
-// Same semantic as MinAlign.
-// -----------------------------------------------------------------------------
-
 inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
 
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
 inline Align commonAlignment(Align A, uint64_t Offset) {
   return Align(MinAlign(A.value(), Offset));
 }
 
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
 inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
   return A && B ? commonAlignment(*A, *B) : A ? A : B;
 }
 
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
 inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
   return MaybeAlign(MinAlign((*A).value(), Offset));
 }
 
-// -----------------------------------------------------------------------------
+/// Returns a representation of the alignment that encodes undefined as 0.
-// Encode/Decode
-// -----------------------------------------------------------------------------
-
-// Returns a more compact representation of the alignment.
-// An undefined MaybeAlign is encoded as 0.
 inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
 
-// Dual operation of the encode function above.
+/// Dual operation of the encode function above.
 inline MaybeAlign decodeMaybeAlign(unsigned Value) {
   if (Value == 0)
     return MaybeAlign();
@@ -186,17 +177,11 @@ inline MaybeAlign decodeMaybeAlign(unsigned Value) {
   return Out;
 }
 
-// Returns a more compact representation of the alignment.
+/// Returns a representation of the alignment, the encoded value is positive by
-// The encoded value is positive by definition.
+/// definition.
-// e.g. Align(1).encode() == 1
-// e.g. Align(16).encode() == 5
 inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
 
-// -----------------------------------------------------------------------------
+/// Comparisons between Align and scalars. Rhs must be positive.
-// Comparisons
-// -----------------------------------------------------------------------------
-
-// Comparisons between Align and scalars. Rhs must be positive.
 inline bool operator==(Align Lhs, uint64_t Rhs) {
   ALIGN_CHECK_ISPOSITIVE(Rhs);
   return Lhs.value() == Rhs;
@@ -222,7 +207,7 @@ inline bool operator>(Align Lhs, uint64_t Rhs) {
   return Lhs.value() > Rhs;
 }
 
-// Comparisons between MaybeAlign and scalars.
+/// Comparisons between MaybeAlign and scalars.
 inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
   return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
 }
@@ -250,7 +235,7 @@ inline bool operator>(MaybeAlign Lhs, uint64_t Rhs) {
   return (*Lhs).value() > Rhs;
 }
 
-// Comparisons operators between Align.
+/// Comparisons operators between Align.
 inline bool operator==(Align Lhs, Align Rhs) {
   return Lhs.ShiftValue == Rhs.ShiftValue;
 }
@@ -270,7 +255,7 @@ inline bool operator>(Align Lhs, Align Rhs) {
   return Lhs.ShiftValue > Rhs.ShiftValue;
 }
 
-// Comparisons operators between Align and MaybeAlign.
+/// Comparisons operators between Align and MaybeAlign.
 inline bool operator==(Align Lhs, MaybeAlign Rhs) {
   ALIGN_CHECK_ISSET(Rhs);
   return Lhs.value() == (*Rhs).value();
@@ -296,7 +281,7 @@ inline bool operator>(Align Lhs, MaybeAlign Rhs) {
   return Lhs.value() > (*Rhs).value();
 }
 
-// Comparisons operators between MaybeAlign and Align.
+/// Comparisons operators between MaybeAlign and Align.
 inline bool operator==(MaybeAlign Lhs, Align Rhs) {
   ALIGN_CHECK_ISSET(Lhs);
   return Lhs && (*Lhs).value() == Rhs.value();
@@ -322,10 +307,6 @@ inline bool operator>(MaybeAlign Lhs, Align Rhs) {
   return Lhs && (*Lhs).value() > Rhs.value();
 }
 
-// -----------------------------------------------------------------------------
-// Division
-// -----------------------------------------------------------------------------
-
 inline Align operator/(Align Lhs, uint64_t Divisor) {
   assert(llvm::isPowerOf2_64(Divisor) &&
          "Divisor must be positive and a power of 2");