[clang][docs] Add documentation for APValue constructors

[tbaederr]

I always get confused when looking at these.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Timm Baeder (tbaederr)

Changes

I always get confused when looking at these.

---

Full diff: https://github.com/llvm/llvm-project/pull/109994.diff

1 Files Affected:

• (modified) clang/include/clang/AST/APValue.h (+40)

diff --git a/clang/include/clang/AST/APValue.h b/clang/include/clang/AST/APValue.h
index c4206b73b11562..61d51523937494 100644
--- a/clang/include/clang/AST/APValue.h
+++ b/clang/include/clang/AST/APValue.h
@@ -314,51 +314,91 @@ class APValue {
   DataType Data;
 
 public:
+  /// Creates an empty APValue of type None.
   APValue() : Kind(None) {}
+  /// Creates an integer APValue holding the given value.
   explicit APValue(APSInt I) : Kind(None) {
     MakeInt(); setInt(std::move(I));
   }
+  /// Creates a float APValue holding the given value.
   explicit APValue(APFloat F) : Kind(None) {
     MakeFloat(); setFloat(std::move(F));
   }
+  /// Creates an fixed-point APValue holding the given value.
   explicit APValue(APFixedPoint FX) : Kind(None) {
     MakeFixedPoint(std::move(FX));
   }
+  /// Creates a vector APValue with \p N elements. The elements
+  /// are read from \p E.
   explicit APValue(const APValue *E, unsigned N) : Kind(None) {
     MakeVector(); setVector(E, N);
   }
+  /// Creates an integer complex APValue with the given real and imaginary
+  /// values.
   APValue(APSInt R, APSInt I) : Kind(None) {
     MakeComplexInt(); setComplexInt(std::move(R), std::move(I));
   }
+  /// Creates a float complex APValue with the given real and imaginary values.
   APValue(APFloat R, APFloat I) : Kind(None) {
     MakeComplexFloat(); setComplexFloat(std::move(R), std::move(I));
   }
   APValue(const APValue &RHS);
   APValue(APValue &&RHS);
+  /// Creates an lvalue APValue without an lvalue path.
+  /// \param B The base of the lvalue.
+  /// \param O The offset of the lvalue.
+  /// \param N Marker. Pass an empty NoValuePath.
+  /// \param IsNullPtr Whether this lvalue is a null pointer.
   APValue(LValueBase B, const CharUnits &O, NoLValuePath N,
           bool IsNullPtr = false)
       : Kind(None) {
     MakeLValue(); setLValue(B, O, N, IsNullPtr);
   }
+  /// Creates an lvalue APValue with an lvalue path.
+  /// \param B The base of the lvalue.
+  /// \param O The offset of the lvalue.
+  /// \param Path The lvalue path.
+  /// \param OnePastTheEnd Whether this lvalue is one-past-the-end of the
+  /// subobject it points to.
+  /// \param IsNullPtr Whether this lvalue is a null pointer.
   APValue(LValueBase B, const CharUnits &O, ArrayRef<LValuePathEntry> Path,
           bool OnePastTheEnd, bool IsNullPtr = false)
       : Kind(None) {
     MakeLValue(); setLValue(B, O, Path, OnePastTheEnd, IsNullPtr);
   }
+  /// Creates a new array APValue.
+  /// \param UninitArray Marker. Pass an empty UninitArray.
+  /// \param InitElts Number of elements you're going to initialize in the
+  /// array.
+  /// \param Size Full size of the array.
   APValue(UninitArray, unsigned InitElts, unsigned Size) : Kind(None) {
     MakeArray(InitElts, Size);
   }
+  /// Creates a new struct APValue.
+  /// \param UninitStruct Marker. Pass an empty UninitStruct.
+  /// \param B Number of bases.
+  /// \param M Number of members.
   APValue(UninitStruct, unsigned B, unsigned M) : Kind(None) {
     MakeStruct(B, M);
   }
+  /// Creates a new union APValue.
+  /// \param D The FieldDecl of the active union member.
+  /// \param V The value of the active union member.
   explicit APValue(const FieldDecl *D, const APValue &V = APValue())
       : Kind(None) {
     MakeUnion(); setUnion(D, V);
   }
+  /// Creates a new member pointer APValue.
+  /// \param Member Declaration of the member
+  /// \param IsDerivedMember Whether member is a derived one.
+  /// \param Path The path of the member.
   APValue(const ValueDecl *Member, bool IsDerivedMember,
           ArrayRef<const CXXRecordDecl*> Path) : Kind(None) {
     MakeMemberPointer(Member, IsDerivedMember, Path);
   }
+  /// Creates a new address label diff APValue.
+  /// \param LHSExpr The left-hand side of the difference.
+  /// \param RHSExpr The right-hand side of the difference.
   APValue(const AddrLabelExpr* LHSExpr, const AddrLabelExpr* RHSExpr)
       : Kind(None) {
     MakeAddrLabelDiff(); setAddrLabelDiff(LHSExpr, RHSExpr);

[Sirraide]

LGTM overall; I just have some minor comments

[Sirraide]

I feel like these parameters should have more descriptive names, because just B meaning ‘number of bases’ is rather horrible

[tbaederr]

Yes, that's one reason why I wrote this patch.

[Sirraide]

Same here actually; not having single-letter parameter names would probably also help...

[Sirraide]

(and imo the NoLValuePath parameter shouldn’t even have a name to indicate it’s really just a marker; you can just make a new one in the call to setLValue() since that’s a no-op anyway)