diff --git a/include/cppgc/allocation.h b/include/cppgc/allocation.h index ac5062ad01..169027d9b9 100644 --- a/include/cppgc/allocation.h +++ b/include/cppgc/allocation.h @@ -118,9 +118,9 @@ class MakeGarbageCollectedTraitBase * that are provided through MakeGarbageCollectedTraitBase. * * Any trait overriding construction must - * - allocate through MakeGarbageCollectedTraitBase::Allocate; + * - allocate through `MakeGarbageCollectedTraitBase::Allocate`; * - mark the object as fully constructed using - * MakeGarbageCollectedTraitBase::MarkObjectAsFullyConstructed; + * `MakeGarbageCollectedTraitBase::MarkObjectAsFullyConstructed`; */ template class MakeGarbageCollectedTrait : public MakeGarbageCollectedTraitBase { diff --git a/include/cppgc/custom-space.h b/include/cppgc/custom-space.h index 975182cad8..11a28cb243 100644 --- a/include/cppgc/custom-space.h +++ b/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: diff --git a/include/cppgc/default-platform.h b/include/cppgc/default-platform.h index be83738b41..28990da92e 100644 --- a/include/cppgc/default-platform.h +++ b/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 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); } diff --git a/include/cppgc/ephemeron-pair.h b/include/cppgc/ephemeron-pair.h index 05c3787a74..47163d3071 100644 --- a/include/cppgc/ephemeron-pair.h +++ b/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 struct EphemeronPair { diff --git a/include/cppgc/garbage-collected.h b/include/cppgc/garbage-collected.h index 3c800ef61b..d28a39074a 100644 --- a/include/cppgc/garbage-collected.h +++ b/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 diff --git a/include/cppgc/heap.h b/include/cppgc/heap.h index 029158f4a5..04a55598bd 100644 --- a/include/cppgc/heap.h +++ b/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> 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: diff --git a/include/cppgc/liveness-broker.h b/include/cppgc/liveness-broker.h index 883be46240..b69a69535b 100644 --- a/include/cppgc/liveness-broker.h +++ b/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 diff --git a/include/cppgc/platform.h b/include/cppgc/platform.h index b6c21bdec0..fb0b6b2082 100644 --- a/include/cppgc/platform.h +++ b/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(...)); * 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 PostJob( - * TaskPriority priority, std::unique_ptr job_task) override { - * return std::make_unique( - * std::make_shared( - * this, std::move(job_task), kNumThreads)); + * A sufficient `PostJob()` implementation that uses the default Job provided + * in libplatform looks like: + * \code + * std::unique_ptr PostJob( + * TaskPriority priority, std::unique_ptr job_task) override { + * return std::make_unique( + * std::make_shared( + * this, std::move(job_task), kNumThreads)); * } + * \endcode */ virtual std::unique_ptr PostJob( TaskPriority priority, std::unique_ptr job_task) { diff --git a/include/cppgc/source-location.h b/include/cppgc/source-location.h index 139c9d86c0..29d69b0a13 100644 --- a/include/cppgc/source-location.h +++ b/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: