cppgc: Another round of API docs

Document:
- TraceCallback
- TraceDescriptor
- TraceTrait

Bug: chromium:1056170
Change-Id: I1c57ce215e4f6f83563326924cfc4c6aeef33e41
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/2235112
Commit-Queue: Michael Lippautz <mlippautz@chromium.org>
Reviewed-by: Omer Katz <omerkatz@chromium.org>
Cr-Commit-Position: refs/heads/master@{#68225}

include/cppgc/allocation.h

@@ -37,8 +37,8 @@ class V8_EXPORT MakeGarbageCollectedTraitInternal {
   }
 
   static void* Allocate(cppgc::Heap* heap, size_t size, GCInfoIndex index);
-  static void* Allocate(cppgc::Heap* heapx, size_t size, GCInfoIndex index,
-                        CustomSpaceIndex space_inde);
+  static void* Allocate(cppgc::Heap* heap, size_t size, GCInfoIndex index,
+                        CustomSpaceIndex space_index);
 
   friend class HeapObjectHeader;
 };

include/cppgc/trace-trait.h

@@ -14,6 +14,8 @@ class Visitor;
 
 namespace internal {
 
+// Implementation of the default TraceTrait handling GarbageCollected and
+// GarbageCollectedMixin.
 template <typename T,
           bool =
               IsGarbageCollectedMixinTypeV<typename std::remove_const<T>::type>>
@@ -21,25 +23,57 @@ struct TraceTraitImpl;
 
 }  // namespace internal
 
-using TraceCallback = void (*)(Visitor*, const void*);
-
-// TraceDescriptor is used to describe how to trace an object.
+/**
+ * Callback for invoking tracing on a given object.
+ *
+ * \param visitor The visitor to dispatch to.
+ * \param object The object to invoke tracing on.
+ */
+using TraceCallback = void (*)(Visitor* visitor, const void* object);
+
+/**
+ * Describes how to trace an object, i.e., how to visit all Oilpan-relevant
+ * fields of an object.
+ */
 struct TraceDescriptor {
-  // The adjusted base pointer of the object that should be traced.
+  /**
+   * Adjusted base pointer, i.e., the pointer to the class inheriting directly
+   * from GarbageCollected, of the object that is being traced.
+   */
   const void* base_object_payload;
-  // A callback for tracing the object.
+  /**
+   * Callback for tracing the object.
+   */
   TraceCallback callback;
 };
 
+/**
+ * Trait specifying how the garbage collector processes an object of type T.
+ *
+ * Advanced users may override handling by creating a specialization for their
+ * type.
+ */
 template <typename T>
 struct TraceTrait {
   static_assert(internal::IsTraceableV<T>, "T must have a Trace() method");
 
+  /**
+   * Accessor for retrieving a TraceDescriptor to process an object of type T.
+   *
+   * \param self The object to be processed.
+   * \returns a TraceDescriptor to process the object.
+   */
   static TraceDescriptor GetTraceDescriptor(const void* self) {
     return internal::TraceTraitImpl<T>::GetTraceDescriptor(
         static_cast<const T*>(self));
   }
 
+  /**
+   * Function invoking the tracing for an object of type T.
+   *
+   * \param visitor The visitor to dispatch to.
+   * \param self The object to invoke tracing on.
+   */
   static void Trace(Visitor* visitor, const void* self) {
     static_cast<const T*>(self)->Trace(visitor);
   }