cppgc: Add some more API documentation

Add docs for:
- cppgc namespace (to have doxygen generate the namespace doc)
- Heap
- LivenessBroker

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

include/cppgc/heap.h

@@ -12,7 +12,11 @@
 #include "cppgc/custom-space.h"
 #include "v8config.h"  // NOLINT(build/include_directory)
 
+/**
+ * cppgc - A C++ garbage collection library.
+ */
 namespace cppgc {
+
 namespace internal {
 class Heap;
 }  // namespace internal
@@ -24,7 +28,16 @@ class V8_EXPORT Heap {
    */
   using StackState = EmbedderStackState;
 
+  /**
+   * Options specifying Heap properties (e.g. custom spaces) when initializing a
+   * heap through Heap::Create().
+   */
   struct HeapOptions {
+    /**
+     * Creates reasonable defaults for instantiating a Heap.
+     *
+     * \returns the HeapOptions that can be passed to Heap::Create().
+     */
     static HeapOptions Default() { return {}; }
 
     /**
@@ -35,7 +48,14 @@ class V8_EXPORT Heap {
     std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces;
   };
 
-  static std::unique_ptr<Heap> Create(HeapOptions = HeapOptions::Default());
+  /**
+   * Creates a new heap that can be used for object allocation.
+   *
+   * \param options HeapOptions specifying various properties for the Heap.
+   * \returns a new Heap instance.
+   */
+  static std::unique_ptr<Heap> Create(
+      HeapOptions options = HeapOptions::Default());
 
   virtual ~Heap() = default;
 

include/cppgc/liveness-broker.h

@@ -16,6 +16,30 @@ namespace internal {
 class LivenessBrokerFactory;
 }  // namespace internal
 
+/**
+ * The broker is passed to weak callbacks to allow (temporarily) querying
+ * the liveness state of an object. References to non-live objects must be
+ * cleared when IsHeapObjectAlive() returns false.
+ *
+ * \code
+ * class GCedWithCustomWeakCallback final
+ *   : public GarbageCollected<GCedWithCustomWeakCallback> {
+ *  public:
+ *   UntracedMember<Bar> bar;
+ *
+ *   void CustomWeakCallbackMethod(const LivenessBroker& broker) {
+ *     if (!broker.IsHeapObjectAlive(bar))
+ *       bar = nullptr;
+ *   }
+ *
+ *   void Trace(cppgc::Visitor* visitor) const {
+ *     visitor->RegisterWeakCallbackMethod<
+ *         GCedWithCustomWeakCallback,
+ *         &GCedWithCustomWeakCallback::CustomWeakCallbackMethod>(this);
+ *   }
+ * };
+ * \endcode
+ */
 class V8_EXPORT LivenessBroker final {
  public:
   template <typename T>