From 5775f02e89a8a069dd0f797c0b0c3d914b23544d Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Mon, 25 Nov 2024 23:24:14 -0800 Subject: [PATCH] Make Doxygen warnings strict (#441) * Make Doxygen warnings strict * Avoid `::symbol` because that doesn't warn on typos * Check the generated HTML for symbols that should not be there --- Doxyfile | 9 ++++++ Makefile | 2 ++ doc/articles/Asynchronous Operations.md | 10 +++--- doc/articles/Errors.md | 10 +++--- doc/articles/Surfaces.md | 38 +++++++++++----------- gen/cheader.tmpl | 16 +++++----- webgpu.h | 42 ++++++++++++------------- webgpu.yml | 26 +++++++-------- 8 files changed, 82 insertions(+), 71 deletions(-) diff --git a/Doxyfile b/Doxyfile index 25d64f43..46330f6c 100644 --- a/Doxyfile +++ b/Doxyfile @@ -27,6 +27,15 @@ OUTPUT_DIRECTORY = doc/generated OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_STATIC = YES +WARN_AS_ERROR = FAIL_ON_WARNINGS +WARN_IF_INCOMPLETE_DOC = NO +# Note EXTRACT_ALL bypasses these, but keep them in case we disable it. +WARN_IF_UNDOC_ENUM_VAL = YES +WARN_NO_PARAMDOC = NO +WARN_IF_UNDOCUMENTED = YES + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- diff --git a/Makefile b/Makefile index 73114a62..bd61f6d3 100644 --- a/Makefile +++ b/Makefile @@ -24,3 +24,5 @@ gen-check: fix gen doc: webgpu.h Doxyfile doxygen Doxyfile + # Verify that no ` or :: made it through into the final docs + ! grep -RE '`|>::' doc/generated/**/*.html diff --git a/doc/articles/Asynchronous Operations.md b/doc/articles/Asynchronous Operations.md index 8270ae0f..570caf31 100644 --- a/doc/articles/Asynchronous Operations.md +++ b/doc/articles/Asynchronous Operations.md @@ -21,7 +21,7 @@ All asynchronous operations start when the application calls an asynchronous web `void* userdata1`
`void* userdata2` -The `callback` function pointer is called when the application _observes completion_ of the asynchronous operation. The `userdata1` and `userdata2` members are passed back to the application as the last two arguments in the callback function. Callbacks **might not** be called unless the application explicitly flushes them in order to _observe completion_. The point in time a callback is called depends on the @ref WGPUCallbackMode of the operation. webgpu.h provides three callback modes: `::WGPUCallbackMode_WaitAnyOnly`, `::WGPUCallbackMode_AllowProcessEvents`, and `::WGPUCallbackMode_AllowSpontaneous`. +The `callback` function pointer is called when the application _observes completion_ of the asynchronous operation. The `userdata1` and `userdata2` members are passed back to the application as the last two arguments in the callback function. Callbacks **might not** be called unless the application explicitly flushes them in order to _observe completion_. The point in time a callback is called depends on the @ref WGPUCallbackMode of the operation. webgpu.h provides three callback modes: @ref WGPUCallbackMode_WaitAnyOnly, @ref WGPUCallbackMode_AllowProcessEvents, and @ref WGPUCallbackMode_AllowSpontaneous. > @copydoc ::WGPUCallbackMode_WaitAnyOnly > @copydoc ::WGPUCallbackMode_AllowProcessEvents @@ -32,13 +32,13 @@ The `callback` function pointer is called when the application _observes complet Waits on any WGPUFuture in the list of `futures` to complete for `timeoutNS` nanoseconds. Returns when at least one `WGPUFuture` is completed or `timeoutNS` elapses, whichever is first. If `timeoutNS` is zero, all `futures` are polled once, without blocking. -Returns `::WGPUWaitStatus_Success` if at least one `WGPUFuture` completes. WGPUFutureWaitInfo::completed is set to true for all completed futures. See @ref WGPUWaitStatus for other status codes. +Returns @ref WGPUWaitStatus_Success if at least one `WGPUFuture` completes. WGPUFutureWaitInfo::completed is set to true for all completed futures. See @ref WGPUWaitStatus for other status codes. Within this call, for any `WGPUFuture`s that completed, their respective callbacks will fire. ### Timed Wait {#Timed-Wait} -Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in `::wgpuCreateInstance` with `WGPUInstanceFeatures::timedWaitAnyEnable`, and the number of futures waited on must be less than or equal to `WGPUInstanceFeatures::timedWaitAnyMaxCount`. Supported instance features may be queried using `::wgpuGetInstanceFeatures`. +Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in @ref wgpuCreateInstance with `WGPUInstanceFeatures::timedWaitAnyEnable`, and the number of futures waited on must be less than or equal to `WGPUInstanceFeatures::timedWaitAnyMaxCount`. Supported instance features may be queried using @ref wgpuGetInstanceCapabilities. ### Mixed Sources {#Mixed-Sources} @@ -59,13 +59,13 @@ Asynchronous operations may originate from different sources. There are CPU-time ## wgpuInstanceProcessEvents {#Process-Events} `void wgpuInstanceProcessEvents(WGPUInstance)` -Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with `::WGPUCallbackMode_AllowProcessEvents` that have completed. This is a non-blocking operation. +Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with @ref WGPUCallbackMode_AllowProcessEvents that have completed. This is a non-blocking operation. ## Device Events Device events are slightly different in that their callback info (`WGPUDeviceLostCallbackInfo` and `WGPUUncapturedErrorCallbackInfo`) are passed on the `WGPUDeviceDescriptor`, instead of in a function argument. There is no `WGPUFuture` returned for either callback. @todo Add a getter for the device lost WGPUFuture. See discussion at https://github.com/webgpu-native/webgpu-headers/issues/199#issuecomment-1866850031. -The `WGPUUncapturedErrorCallbackInfo` _does not_ have a callback mode member. It is always as-if it were `::WGPUCallbackMode_AllowSpontaneous`. Note also that the uncaptured error callback is a _repeating_ callback that fires multiple times, unlike other callbacks in webgpu.h. +The `WGPUUncapturedErrorCallbackInfo` _does not_ have a callback mode member. It is always as-if it were @ref WGPUCallbackMode_AllowSpontaneous. Note also that the uncaptured error callback is a _repeating_ callback that fires multiple times, unlike other callbacks in webgpu.h. The uncaptured error callback is guaranteed not to fire after the device becomes lost. When the device is lost, it is an appropriate time for the application to free userdata variables for the uncaptured error callback. Note that the device becomes lost _before_ the actual device lost callback fires. First the device state transitions to lost, then the device lost callback fires. The timing of the callback depends on the device lost callback mode. diff --git a/doc/articles/Errors.md b/doc/articles/Errors.md index 4f5d1fcf..8c6fd710 100644 --- a/doc/articles/Errors.md +++ b/doc/articles/Errors.md @@ -25,7 +25,7 @@ These behave similarly to the Promise-returning JavaScript APIs. Instead of ther These errors include: -- @ref SynchronousStructChainingError cases. +- @ref StructChainingError cases. - [Content-timeline](https://www.w3.org/TR/webgpu/#content-timeline) errors other than those which are surfaced as @ref DeviceError in `webgpu.h`. See specific documentation to determine how each error is exposed. Generally these will return some kind of failure status (like \ref WGPUStatus_Error) or `NULL`, and produce an @ref ImplementationDefinedLogging message. @@ -36,15 +36,15 @@ Entry points may also specify that they produce "implementation-defined logging" These messages are logged in an implementation defined way (e.g. to an implementation-specific callback, or to a logging runtime). They are intended to be intended to be read by humans, useful primarily for development and crash reporting. -## Struct-Chaining Errors {#StructChainingErrors} +## Struct-Chaining Error {#StructChainingError} -A struct-chaining error happens when the @ref SType of a struct in a struct chain is not valid for that chain. +A struct-chaining error happens when the @ref WGPUSType of a struct in a struct chain is not valid for that chain. -Struct chains which are used in device-timeline validation/operations (e.g. @ref WGPUBufferDescriptor in @ref WGPUDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error. +Struct chains which are used in device-timeline validation/operations (e.g. @ref WGPUBufferDescriptor in @ref wgpuDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error. ### Out-Struct-Chain Error {#OutStructChainError} -Operations which take out-struct-chains (e.g. @ref WGPULimits, in @ref WGPUAdapterGetLimits/@ref WGPUDeviceGetLimits, but not in @ref WGPUDeviceDescriptor) handle struct-chaining errors as follows: +Operations which take out-struct-chains (e.g. @ref WGPULimits, in @ref wgpuAdapterGetLimits and @ref wgpuDeviceGetLimits, but not in @ref WGPUDeviceDescriptor) handle struct-chaining errors as follows: - The output struct and struct chain is not modified. - The operation produces a @ref SynchronousError (return value and log message). diff --git a/doc/articles/Surfaces.md b/doc/articles/Surfaces.md index 6c7a20ac..531577a4 100644 --- a/doc/articles/Surfaces.md +++ b/doc/articles/Surfaces.md @@ -11,7 +11,7 @@ Sections below give more details about these operations, including the specifica ## Surface Creation {#Surface-Creation} -A @ref WGPUSurface is child object of a @ref WGPUInstance and created using `::wgpuInstanceCreateSurface`. +A @ref WGPUSurface is child object of a @ref WGPUInstance and created using @ref wgpuInstanceCreateSurface. The description of a @ref WGPUSurface is a @ref WGPUSurfaceDescriptor with a sub-descriptor chained containing the environment-specific objects used to identify the surface. Surfaces that can be presented to using `webgpu.h` (but not necessarily by all implementations) are: @@ -56,9 +56,9 @@ struct WGPUSurface { }; ``` -The behavior of `::wgpuInstanceCreateSurface``(instance, descriptor)` is: +The behavior of @ref wgpuInstanceCreateSurface(instance, descriptor) is: - - If any of these validation steps fails, return an error @ref WGPUSurface: + - If any of these validation steps fails, return an error @ref WGPUSurface object: - Validate that all the sub-descriptors in the chain for `descriptor` are known to this implementation. - Validate that `descriptor` contains information about exactly one OS surface. @@ -70,16 +70,16 @@ The behavior of `::wgpuInstanceCreateSurface``(instance, descriptor)` is: Depending on the OS, GPU used, backing API for WebGPU and other factors, different capabilities are available to render and present the @ref WGPUSurface. For this reason, negotiation is done between the WebGPU implementation and the application to choose how to use the @ref WGPUSurface. -This first step of the negotiation is querying what capabilities are available using `::wgpuSurfaceGetCapabilities` that fills an @ref WGPUSurfaceCapabilities structure with the following information: +This first step of the negotiation is querying what capabilities are available using @ref wgpuSurfaceGetCapabilities that fills an @ref WGPUSurfaceCapabilities structure with the following information: - A bit set of supported @ref WGPUTextureUsage that are guaranteed to contain @ref WGPUTextureUsage_RenderAttachment. - A list of supported @ref WGPUTextureFormat values, in order of preference. - A list of supported @ref WGPUPresentMode values (guaranteed to contain @ref WGPUPresentMode_Fifo). - A list of supported @ref WGPUCompositeAlphaMode values (@ref WGPUCompositeAlphaMode_Auto is always supported but never listed in capabilities as it just lets the implementation decide what to use). -The call to `::wgpuSurfaceGetCapabilities` may allocate memory for pointers filled in the @ref WGPUSurfaceCapabilities structure so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid leaking memory once the capabilities are no longer needed. +The call to @ref wgpuSurfaceGetCapabilities may allocate memory for pointers filled in the @ref WGPUSurfaceCapabilities structure so @ref wgpuSurfaceCapabilitiesFreeMembers must be called to avoid leaking memory once the capabilities are no longer needed. -This is an example of how to query the capabilities or a @ref WGPUSurface: +This is an example of how to query the capabilities of a @ref WGPUSurface: ```c // Get the capabilities @@ -103,7 +103,7 @@ for (size_t i = 0; i < caps.presentModeCount; i++) { wgpuSurfaceCapabilitiesFreeMembers(caps); ``` -The behavior of `::wgpuSurfaceGetCapabilities``(surface, adapter, caps)` is: +The behavior of @ref wgpuSurfaceGetCapabilities(surface, adapter, caps) is: - If any of these validation steps fails, return false. (TODO return an error WGPUStatus): @@ -116,14 +116,14 @@ The behavior of `::wgpuSurfaceGetCapabilities``(surface, adapter, caps)` is: ## Surface Configuration {#Surface-Configuration} Before it can use it for rendering, the application must configure the surface. -The configuration is the second step of the negotiation, done after analyzing the results of `::wgpuSurfaceGetCapabilities`. +The configuration is the second step of the negotiation, done after analyzing the results of @ref wgpuSurfaceGetCapabilities. It contains the following kinds of parameters: - The @ref WGPUDevice that will be used to render to the surface. - - Parameters for the textures returned by `::wgpuSurfaceGetCurrentTexture`. + - Parameters for the textures returned by @ref wgpuSurfaceGetCurrentTexture. - @ref WGPUPresentMode and @ref WGPUCompositeAlphaMode parameters for how and when the surface will be presented to the user. -This is an example of how to configure a @ref WGPUSurface: +This is an example of how to configure a @ref WGPUSurface: ```c WGPUSurfaceConfiguration config = { @@ -163,13 +163,13 @@ WGPUTextureDescriptor GetSurfaceEquivalentTextureDescriptor(const WGPUSurfaceCon When a surface is successfully configured, the new configuration overrides any previous configuration and destroys the previous current texture (if any) so it can no longer be used. -The behavior of `::wgpuSurfaceConfigure``(surface, config)` is: +The behavior of @ref wgpuSurfaceConfigure(surface, config) is: - If any of these validation steps fails, TODO: what should happen on failure? - Validate that `surface` is not an error. - Let `adapter` be the adapter used to create `device`. - - Let `caps` be the @ref WGPUSurfaceCapabilities filled with `::wgpuSurfaceGetCapabilities``(surface, adapter, &caps)`. + - Let `caps` be the @ref WGPUSurfaceCapabilities filled with @ref wgpuSurfaceGetCapabilities(surface, adapter, &caps). - Validate that all the sub-descriptors in the chain for `caps` are known to this implementation. - Validate that `device` is alive. - Validate that `config->presentMode` is in `caps->presentModes`. @@ -182,23 +182,23 @@ The behavior of `::wgpuSurfaceConfigure``(surface, config)` is: - Set `surface.config` to a deep copy of `config`. - If `surface.currentFrame` is not `None`: - - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called. + - Do as if @ref wgpuTextureDestroy(surface.currentFrame) was called. - Set `surface.currentFrame` to `None`. It can also be useful to remove the configuration of a @ref WGPUSurface without replacing it with a valid one. Without removing the configuration, the @ref WGPUSurface will keep referencing the @ref WGPUDevice that cannot be totally reclaimed. -The behavior of `::wgpuSurfaceUnconfigure``()` is: +The behavior of @ref wgpuSurfaceUnconfigure() is: - Set `surface.config` to `None`. - If `surface.currentFrame` is not `None`: - - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called. + - Do as if @ref wgpuTextureDestroy(surface.currentFrame) was called. - Set `surface.currentFrame` to `None`. ## Presenting to Surface {#Surface-Presenting} -Each frame, the application retrieves the @ref WGPUTexture for the frame with `::wgpuSurfaceGetCurrentTexture`, renders to it and then presents it on the screen with `::wgpuSurfacePresent`. +Each frame, the application retrieves the @ref WGPUTexture for the frame with @ref wgpuSurfaceGetCurrentTexture, renders to it and then presents it on the screen with @ref wgpuSurfacePresent. Issues can happen when trying to retrieve the frame's @ref WGPUTexture, so the application must check @ref WGPUSurfaceTexture `.status` to see if the surface or the device was lost, or some other windowing system issue caused a timeout. The environment can also change the surface without breaking it, but making the current configuration suboptimal. @@ -234,7 +234,7 @@ wgpuTextureRelease(surfaceTexture.texture); ``` -The behavior of `::wgpuSurfaceGetCurrentTexture``(surface, surfaceTexture)` is: +The behavior of @ref wgpuSurfaceGetCurrentTexture(surface, surfaceTexture) is: 1. Set `surfaceTexture->texture` to `NULL`. 1. If any of these validation steps fails, set `surfaceTexture->status` to `WGPUSurfaceGetCurrentTextureStatus_Error` and return (TODO send error to device?). @@ -255,13 +255,13 @@ The behavior of `::wgpuSurfaceGetCurrentTexture``(surface, surfaceTexture)` is: 1. Add a new reference to `t`. 1. Set `surfaceTexture->texture` to a new reference to `t`. -The behavior of `::wgpuSurfacePresent``(surface)` is: +The behavior of @ref wgpuSurfacePresent(surface) is: - If any of these validation steps fails, TODO send error to device? - Validate that `surface` is not an error. - Validate that `surface.currentFrame` is not `None`. - - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called. + - Do as if @ref wgpuTextureDestroy(surface.currentFrame) was called. - Present `surface.currentFrame` to the `surface`. - Set `surface.currentFrame` to `None`. diff --git a/gen/cheader.tmpl b/gen/cheader.tmpl index 67bae1c1..898dacb5 100644 --- a/gen/cheader.tmpl +++ b/gen/cheader.tmpl @@ -86,7 +86,7 @@ {{end}} /** - * \defgroup Constants + * \defgroup Constants Constants * \brief Constants. * * @{ @@ -159,7 +159,7 @@ typedef {{CType .Type "" ""}} WGPU{{.Name | PascalCase}}{{$.ExtSuffix}}; /** @} */ /** - * \defgroup Objects + * \defgroup Objects Objects * \brief Opaque, non-dispatchable handles to WebGPU objects. * * @{ @@ -191,7 +191,7 @@ struct WGPU{{.Name | PascalCase}}CallbackInfo{{$.ExtSuffix}}; {{ end}} /** - * \defgroup Enumerations + * \defgroup Enumerations Enumerations * \brief Enums. * * @{ @@ -221,7 +221,7 @@ typedef enum WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} { /** @} */ /** - * \defgroup Bitflags + * \defgroup Bitflags Bitflags * \brief Type and constant definitions for bitflag types. * * @{ @@ -243,7 +243,7 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE; {{ end}} /** - * \defgroup Callbacks + * \defgroup Callbacks Callbacks * \brief Callbacks through which asynchronous functions return. * * @{ @@ -278,14 +278,14 @@ typedef struct WGPUChainedStructOut { {{ end}} /** - * \defgroup Structures + * \defgroup Structures Structures * \brief Descriptors and other transparent structures. * * @{ */ /** - * \defgroup WGPUCallbackInfo + * \defgroup WGPUCallbackInfo Callback Info Structs * \brief Callback info structures that are used in asynchronous functions. * * @{ @@ -439,7 +439,7 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUStringView procName) WGPU_FUNCTION_A /** @} */ /** - * \defgroup Methods + * \defgroup Methods Methods * \brief Functions that are relative to a specific object. * * @{ diff --git a/webgpu.h b/webgpu.h index 545e7975..efc4fe38 100644 --- a/webgpu.h +++ b/webgpu.h @@ -75,7 +75,7 @@ /** - * \defgroup Constants + * \defgroup Constants Constants * \brief Constants. * * @{ @@ -150,7 +150,7 @@ typedef struct WGPUStringView { /** @} */ /** - * \defgroup Objects + * \defgroup Objects Objects * \brief Opaque, non-dispatchable handles to WebGPU objects. * * @{ @@ -271,7 +271,7 @@ struct WGPUUncapturedErrorCallbackInfo; /** - * \defgroup Enumerations + * \defgroup Enumerations Enumerations * \brief Enums. * * @{ @@ -386,15 +386,15 @@ typedef enum WGPUCallbackMode { /** * `0x00000001`. * Callbacks created with `WGPUCallbackMode_WaitAnyOnly`: - * - fire when the asynchronous operation's future is passed to a call to `::wgpuInstanceWaitAny` - * AND the operation has already completed or it completes inside the call to `::wgpuInstanceWaitAny`. + * - fire when the asynchronous operation's future is passed to a call to @ref wgpuInstanceWaitAny + * AND the operation has already completed or it completes inside the call to @ref wgpuInstanceWaitAny. */ WGPUCallbackMode_WaitAnyOnly = 0x00000001, /** * `0x00000002`. * Callbacks created with `WGPUCallbackMode_AllowProcessEvents`: * - fire for the same reasons as callbacks created with `WGPUCallbackMode_WaitAnyOnly` - * - fire inside a call to `::wgpuInstanceProcessEvents` if the asynchronous operation is complete. + * - fire inside a call to @ref wgpuInstanceProcessEvents if the asynchronous operation is complete. */ WGPUCallbackMode_AllowProcessEvents = 0x00000002, /** @@ -443,7 +443,7 @@ typedef enum WGPUCompilationMessageType { } WGPUCompilationMessageType WGPU_ENUM_ATTRIBUTE; /** - * Describes how frames are composited with other contents on the screen when `::wgpuSurfacePresent` is called. + * Describes how frames are composited with other contents on the screen when @ref wgpuSurfacePresent is called. */ typedef enum WGPUCompositeAlphaMode { /** @@ -658,7 +658,7 @@ typedef enum WGPUPowerPreference { } WGPUPowerPreference WGPU_ENUM_ATTRIBUTE; /** - * Describes when and in which order frames are presented on the screen when `::wgpuSurfacePresent` is called. + * Describes when and in which order frames are presented on the screen when @ref wgpuSurfacePresent is called. */ typedef enum WGPUPresentMode { /** @@ -828,7 +828,7 @@ typedef enum WGPUStoreOp { } WGPUStoreOp WGPU_ENUM_ATTRIBUTE; /** - * The status enum for `::wgpuSurfaceGetCurrentTexture`. + * The status enum for @ref wgpuSurfaceGetCurrentTexture. */ typedef enum WGPUSurfaceGetCurrentTextureStatus { /** @@ -1139,7 +1139,7 @@ typedef enum WGPUWaitStatus { /** @} */ /** - * \defgroup Bitflags + * \defgroup Bitflags Bitflags * \brief Type and constant definitions for bitflag types. * * @{ @@ -1190,7 +1190,7 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE; /** - * \defgroup Callbacks + * \defgroup Callbacks Callbacks * \brief Callbacks through which asynchronous functions return. * * @{ @@ -1245,7 +1245,7 @@ typedef void (*WGPUDeviceLostCallback)(WGPUDevice const * device, WGPUDeviceLost * If the `status` is not @ref WGPUPopErrorScopeStatus_Success, this is @ref WGPUErrorType_NoError. * * @param message - * If the `status` is not @ref WGPUPopeErrorScopeStatus_Success` **or** + * If the `status` is not @ref WGPUPopErrorScopeStatus_Success **or** * the `type` is not @ref WGPUErrorType_NoError, this is a non-empty * @ref LocalizableHumanReadableMessageString; * otherwise, this is an empty string. @@ -1309,14 +1309,14 @@ typedef struct WGPUChainedStructOut { /** - * \defgroup Structures + * \defgroup Structures Structures * \brief Descriptors and other transparent structures. * * @{ */ /** - * \defgroup WGPUCallbackInfo + * \defgroup WGPUCallbackInfo Callback Info Structs * \brief Callback info structures that are used in asynchronous functions. * * @{ @@ -2837,7 +2837,7 @@ typedef struct WGPUSupportedWGSLLanguageFeatures { }) /** - * Filled by `::wgpuSurfaceGetCapabilities` with what's supported for `::wgpuSurfaceConfigure` for a pair of @ref WGPUSurface and @ref WGPUAdapter. + * Filled by @ref wgpuSurfaceGetCapabilities with what's supported for @ref wgpuSurfaceConfigure for a pair of @ref WGPUSurface and @ref WGPUAdapter. * * Default values can be set using @ref WGPU_SURFACE_CAPABILITIES_INIT as initializer. */ @@ -2890,7 +2890,7 @@ typedef struct WGPUSurfaceCapabilities { }) /** - * Options to `::wgpuSurfaceConfigure` for defining how a @ref WGPUSurface will be rendered to and presented to the user. + * Options to @ref wgpuSurfaceConfigure for defining how a @ref WGPUSurface will be rendered to and presented to the user. * See @ref Surface-Configuration for more details. * * Default values can be set using @ref WGPU_SURFACE_CONFIGURATION_INIT as initializer. @@ -2965,7 +2965,7 @@ typedef struct WGPUSurfaceConfiguration { }) /** - * The root descriptor for the creation of an @ref WGPUSurface with `::wgpuInstanceCreateSurface`. + * The root descriptor for the creation of an @ref WGPUSurface with @ref wgpuInstanceCreateSurface. * It isn't sufficient by itself and must have one of the `WGPUSurfaceSource*` in its chain. * See @ref Surface-Creation for more details. * @@ -3192,7 +3192,7 @@ typedef struct WGPUSurfaceTexture { */ WGPUTexture texture; /** - * Whether the call to `::wgpuSurfaceGetCurrentTexture` succeeded and a hint as to why it might not have. + * Whether the call to @ref wgpuSurfaceGetCurrentTexture succeeded and a hint as to why it might not have. * * The `INIT` macro sets this to (@ref WGPUSurfaceGetCurrentTextureStatus)0. */ @@ -5195,7 +5195,7 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUStringView procName) WGPU_FUNCTION_A /** @} */ /** - * \defgroup Methods + * \defgroup Methods Methods * \brief Functions that are relative to a specific object. * * @{ @@ -5479,7 +5479,7 @@ WGPU_EXPORT WGPUSurface wgpuInstanceCreateSurface(WGPUInstance instance, WGPUSur WGPU_EXPORT WGPUStatus wgpuInstanceGetWGSLLanguageFeatures(WGPUInstance instance, WGPUSupportedWGSLLanguageFeatures * features) WGPU_FUNCTION_ATTRIBUTE; WGPU_EXPORT WGPUBool wgpuInstanceHasWGSLLanguageFeature(WGPUInstance instance, WGPUWGSLLanguageFeatureName feature) WGPU_FUNCTION_ATTRIBUTE; /** - * Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with `::WGPUCallbackMode_AllowProcessEvents`. + * Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with @ref WGPUCallbackMode_AllowProcessEvents. * * See @ref Process-Events for more information. */ @@ -5711,7 +5711,7 @@ WGPU_EXPORT void wgpuSurfaceConfigure(WGPUSurface surface, WGPUSurfaceConfigurat * * @param capabilities * The structure to fill capabilities in. - * It may contain memory allocations so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid memory leaks. + * It may contain memory allocations so @ref wgpuSurfaceCapabilitiesFreeMembers must be called to avoid memory leaks. * This parameter is @ref ReturnedWithOwnership. * * @returns diff --git a/webgpu.yml b/webgpu.yml index 09de10e3..068a6c76 100644 --- a/webgpu.yml +++ b/webgpu.yml @@ -229,13 +229,13 @@ enums: - name: wait_any_only doc: | Callbacks created with `WGPUCallbackMode_WaitAnyOnly`: - - fire when the asynchronous operation's future is passed to a call to `::wgpuInstanceWaitAny` - AND the operation has already completed or it completes inside the call to `::wgpuInstanceWaitAny`. + - fire when the asynchronous operation's future is passed to a call to @ref wgpuInstanceWaitAny + AND the operation has already completed or it completes inside the call to @ref wgpuInstanceWaitAny. - name: allow_process_events doc: | Callbacks created with `WGPUCallbackMode_AllowProcessEvents`: - fire for the same reasons as callbacks created with `WGPUCallbackMode_WaitAnyOnly` - - fire inside a call to `::wgpuInstanceProcessEvents` if the asynchronous operation is complete. + - fire inside a call to @ref wgpuInstanceProcessEvents if the asynchronous operation is complete. - name: allow_spontaneous doc: | Callbacks created with `WGPUCallbackMode_AllowSpontaneous`: @@ -304,7 +304,7 @@ enums: doc: | TODO - name: composite_alpha_mode - doc: Describes how frames are composited with other contents on the screen when `::wgpuSurfacePresent` is called. + doc: Describes how frames are composited with other contents on the screen when @ref wgpuSurfacePresent is called. entries: - name: auto doc: Lets the WebGPU implementation choose the best mode (supported, and with the best performance) between @ref WGPUCompositeAlphaMode_Opaque or @ref WGPUCompositeAlphaMode_Inherit. @@ -583,7 +583,7 @@ enums: doc: | TODO - name: present_mode - doc: Describes when and in which order frames are presented on the screen when `::wgpuSurfacePresent` is called. + doc: Describes when and in which order frames are presented on the screen when @ref wgpuSurfacePresent is called. entries: - name: undefined doc: | @@ -810,7 +810,7 @@ enums: doc: | TODO - name: surface_get_current_texture_status - doc: The status enum for `::wgpuSurfaceGetCurrentTexture`. + doc: The status enum for @ref wgpuSurfaceGetCurrentTexture. entries: - null - name: success_optimal @@ -2758,7 +2758,7 @@ structs: type: array pointer: immutable - name: surface_capabilities - doc: Filled by `::wgpuSurfaceGetCapabilities` with what's supported for `::wgpuSurfaceConfigure` for a pair of @ref WGPUSurface and @ref WGPUAdapter. + doc: Filled by @ref wgpuSurfaceGetCapabilities with what's supported for @ref wgpuSurfaceConfigure for a pair of @ref WGPUSurface and @ref WGPUAdapter. type: base_out free_members: true members: @@ -2785,7 +2785,7 @@ structs: pointer: immutable - name: surface_configuration doc: | - Options to `::wgpuSurfaceConfigure` for defining how a @ref WGPUSurface will be rendered to and presented to the user. + Options to @ref wgpuSurfaceConfigure for defining how a @ref WGPUSurface will be rendered to and presented to the user. See @ref Surface-Configuration for more details. type: base_in members: @@ -2820,7 +2820,7 @@ structs: default: fifo - name: surface_descriptor doc: | - The root descriptor for the creation of an @ref WGPUSurface with `::wgpuInstanceCreateSurface`. + The root descriptor for the creation of an @ref WGPUSurface with @ref wgpuInstanceCreateSurface. It isn't sufficient by itself and must have one of the `WGPUSurfaceSource*` in its chain. See @ref Surface-Creation for more details. type: base_in @@ -2916,7 +2916,7 @@ structs: It is @ref ReturnedWithOwnership from @ref wgpuSurfaceGetCurrentTexture. type: object.texture - name: status - doc: Whether the call to `::wgpuSurfaceGetCurrentTexture` succeeded and a hint as to why it might not have. + doc: Whether the call to @ref wgpuSurfaceGetCurrentTexture succeeded and a hint as to why it might not have. type: enum.surface_get_current_texture_status - name: texel_copy_buffer_info doc: | @@ -3248,7 +3248,7 @@ callbacks: type: enum.error_type - name: message doc: | - If the `status` is not @ref WGPUPopeErrorScopeStatus_Success` **or** + If the `status` is not @ref WGPUPopErrorScopeStatus_Success **or** the `type` is not @ref WGPUErrorType_NoError, this is a non-empty @ref LocalizableHumanReadableMessageString; otherwise, this is an empty string. @@ -4186,7 +4186,7 @@ objects: type: enum.WGSL_language_feature_name - name: process_events doc: | - Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with `::WGPUCallbackMode_AllowProcessEvents`. + Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with @ref WGPUCallbackMode_AllowProcessEvents. See @ref Process-Events for more information. - name: request_adapter @@ -4868,7 +4868,7 @@ objects: - name: capabilities doc: | The structure to fill capabilities in. - It may contain memory allocations so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid memory leaks. + It may contain memory allocations so @ref wgpuSurfaceCapabilitiesFreeMembers must be called to avoid memory leaks. type: struct.surface_capabilities pointer: mutable passed_with_ownership: true