cppgc: Improve API documentation

- Use backticks to create cross-refs (https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++-dos-and-donts.md#comment-style)
- More API docs

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

include/cppgc/allocation.h

@@ -118,9 +118,9 @@ class MakeGarbageCollectedTraitBase
  * that are provided through MakeGarbageCollectedTraitBase.
  *
  * Any trait overriding construction must
- * - allocate through MakeGarbageCollectedTraitBase<T>::Allocate;
+ * - allocate through `MakeGarbageCollectedTraitBase<T>::Allocate`;
  * - mark the object as fully constructed using
- *   MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed;
+ *   `MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed`;
  */
 template <typename T>
 class MakeGarbageCollectedTrait : public MakeGarbageCollectedTraitBase<T> {

include/cppgc/custom-space.h

@@ -29,7 +29,7 @@ class CustomSpaceBase {
 
 /**
  * Base class custom spaces should directly inherit from. The class inheriting
- * from CustomSpace must define kSpaceIndex as unique space index. These
+ * from `CustomSpace` must define `kSpaceIndex` as unique space index. These
  * indices need for form a sequence starting at 0.
  *
  * Example:

include/cppgc/default-platform.h

@@ -16,7 +16,7 @@ namespace cppgc {
 
 /**
  * Platform provided by cppgc. Uses V8's DefaultPlatform provided by
- * libplatform internally.Exception: GetForegroundTaskRunner(), see below.
+ * libplatform internally. Exception: `GetForegroundTaskRunner()`, see below.
  */
 class V8_EXPORT DefaultPlatform : public Platform {
  public:
@@ -37,7 +37,7 @@ class V8_EXPORT DefaultPlatform : public Platform {
 
   std::shared_ptr<cppgc::TaskRunner> GetForegroundTaskRunner() override {
     // V8's default platform creates a new task runner when passed the
-    // v8::Isolate pointer the first time. For non-default platforms this will
+    // `v8::Isolate` pointer the first time. For non-default platforms this will
     // require getting the appropriate task runner.
     return v8_platform_->GetForegroundTaskRunner(kNoIsolate);
   }

include/cppgc/ephemeron-pair.h

@@ -11,7 +11,7 @@ namespace cppgc {
 
 /**
  * An ephemeron pair is used to conditionally retain an object.
- * The |value| will be kept alive only if the |key| is alive.
+ * The `value` will be kept alive only if the `key` is alive.
  */
 template <typename K, typename V>
 struct EphemeronPair {

include/cppgc/garbage-collected.h

@@ -39,8 +39,8 @@ class GarbageCollectedBase {
 }  // namespace internal
 
 /**
- * Base class for managed objects. Only descendent types of GarbageCollected
- * can be constructed using MakeGarbageCollected. Must be inherited from as
+ * Base class for managed objects. Only descendent types of `GarbageCollected`
+ * can be constructed using `MakeGarbageCollected()`. Must be inherited from as
  * left-most base class.
  *
  * Types inheriting from GarbageCollected must provide a method of

include/cppgc/heap.h

@@ -66,20 +66,20 @@ class V8_EXPORT Heap {
 
   /**
    * Options specifying Heap properties (e.g. custom spaces) when initializing a
-   * heap through Heap::Create().
+   * heap through `Heap::Create()`.
    */
   struct HeapOptions {
     /**
      * Creates reasonable defaults for instantiating a Heap.
      *
-     * \returns the HeapOptions that can be passed to Heap::Create().
+     * \returns the HeapOptions that can be passed to `Heap::Create()`.
      */
     static HeapOptions Default() { return {}; }
 
     /**
      * Custom spaces added to heap are required to have indices forming a
-     * numbered sequence starting at 0, i.e., their kSpaceIndex must correspond
-     * to the index they reside in the vector.
+     * numbered sequence starting at 0, i.e., their `kSpaceIndex` must
+     * correspond to the index they reside in the vector.
      */
     std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces;
 
@@ -89,7 +89,7 @@ class V8_EXPORT Heap {
      * garbage collections using non-nestable task, which are guaranteed to have
      * no interesting stack, through the provided Platform. If such tasks are
      * not supported by the Platform, the embedder must take care of invoking
-     * the GC through ForceGarbageCollectionSlow().
+     * the GC through `ForceGarbageCollectionSlow()`.
      */
     StackSupport stack_support = StackSupport::kSupportsConservativeStackScan;
 
@@ -126,6 +126,10 @@ class V8_EXPORT Heap {
       const char* source, const char* reason,
       StackState stack_state = StackState::kMayContainHeapPointers);
 
+  /**
+   * \returns the opaque handle for allocating objects using
+   * `MakeGarbageCollected()`.
+   */
   AllocationHandle& GetAllocationHandle();
 
  private:

include/cppgc/liveness-broker.h

@@ -19,7 +19,7 @@ class LivenessBrokerFactory;
 /**
  * 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.
+ * cleared when `IsHeapObjectAlive()` returns false.
  *
  * \code
  * class GCedWithCustomWeakCallback final

include/cppgc/platform.h

@@ -51,22 +51,23 @@ class V8_EXPORT Platform {
   }
 
   /**
-   * Posts |job_task| to run in parallel. Returns a JobHandle associated with
-   * the Job, which can be joined or canceled.
+   * Posts `job_task` to run in parallel. Returns a `JobHandle` associated with
+   * the `Job`, which can be joined or canceled.
    * This avoids degenerate cases:
-   * - Calling CallOnWorkerThread() for each work item, causing significant
+   * - Calling `CallOnWorkerThread()` for each work item, causing significant
    *   overhead.
-   * - Fixed number of CallOnWorkerThread() calls that split the work and might
-   *   run for a long time. This is problematic when many components post
+   * - Fixed number of `CallOnWorkerThread()` calls that split the work and
+   *   might run for a long time. This is problematic when many components post
    *   "num cores" tasks and all expect to use all the cores. In these cases,
    *   the scheduler lacks context to be fair to multiple same-priority requests
    *   and/or ability to request lower priority work to yield when high priority
    *   work comes in.
-   * A canonical implementation of |job_task| looks like:
+   * A canonical implementation of `job_task` looks like:
+   * \code
    * class MyJobTask : public JobTask {
    *  public:
    *   MyJobTask(...) : worker_queue_(...) {}
-   *   // JobTask:
+   *   // JobTask implementation.
    *   void Run(JobDelegate* delegate) override {
    *     while (!delegate->ShouldYield()) {
    *       // Smallest unit of work.
@@ -80,28 +81,33 @@ class V8_EXPORT Platform {
    *     return worker_queue_.GetSize(); // Thread safe.
    *   }
    * };
+   *
+   * // ...
    * auto handle = PostJob(TaskPriority::kUserVisible,
    *                       std::make_unique<MyJobTask>(...));
    * handle->Join();
+   * \endcode
    *
-   * PostJob() and methods of the returned JobHandle/JobDelegate, must never be
-   * called while holding a lock that could be acquired by JobTask::Run or
-   * JobTask::GetMaxConcurrency -- that could result in a deadlock. This is
-   * because [1] JobTask::GetMaxConcurrency may be invoked while holding
-   * internal lock (A), hence JobTask::GetMaxConcurrency can only use a lock (B)
-   * if that lock is *never* held while calling back into JobHandle from any
-   * thread (A=>B/B=>A deadlock) and [2] JobTask::Run or
-   * JobTask::GetMaxConcurrency may be invoked synchronously from JobHandle
-   * (B=>JobHandle::foo=>B deadlock).
+   * `PostJob()` and methods of the returned JobHandle/JobDelegate, must never
+   * be called while holding a lock that could be acquired by `JobTask::Run()`
+   * or `JobTask::GetMaxConcurrency()` -- that could result in a deadlock. This
+   * is because (1) `JobTask::GetMaxConcurrency()` may be invoked while holding
+   * internal lock (A), hence `JobTask::GetMaxConcurrency()` can only use a lock
+   * (B) if that lock is *never* held while calling back into `JobHandle` from
+   * any thread (A=>B/B=>A deadlock) and (2) `JobTask::Run()` or
+   * `JobTask::GetMaxConcurrency()` may be invoked synchronously from
+   * `JobHandle` (B=>JobHandle::foo=>B deadlock).
    *
-   * A sufficient PostJob() implementation that uses the default Job provided in
-   * libplatform looks like:
-   *  std::unique_ptr<JobHandle> PostJob(
-   *      TaskPriority priority, std::unique_ptr<JobTask> job_task) override {
-   *    return std::make_unique<DefaultJobHandle>(
-   *        std::make_shared<DefaultJobState>(
-   *            this, std::move(job_task), kNumThreads));
+   * A sufficient `PostJob()` implementation that uses the default Job provided
+   * in libplatform looks like:
+   * \code
+   * std::unique_ptr<JobHandle> PostJob(
+   *     TaskPriority priority, std::unique_ptr<JobTask> job_task) override {
+   *   return std::make_unique<DefaultJobHandle>(
+   *       std::make_shared<DefaultJobState>(
+   *           this, std::move(job_task), kNumThreads));
    * }
+   * \endcode
    */
   virtual std::unique_ptr<JobHandle> PostJob(
       TaskPriority priority, std::unique_ptr<JobTask> job_task) {

include/cppgc/source-location.h

@@ -25,7 +25,7 @@ namespace cppgc {
 
 /**
  * Encapsulates source location information. Mimics C++20's
- * std::source_location.
+ * `std::source_location`.
  */
 class V8_EXPORT SourceLocation final {
  public: