Tracking issue to write spec / explainers for native-specific parts of webgpu.h

[Kangz]

Most of the behavior of webgpu.h is the same as the WebGPU API (normative reference) but there's a couple places where webgpu.h has non-trivial differences with WebGPU, and it also has native-specific APIs. This is a tracking issue to create initial explainers / spec for these parts.

Things that are very different in native:

• Swapchain / Surface questions #24: surface creation and swapchains
• Instance / adapters and device creation
  not very different anymore
• Event loop Futures
  Covered in Asynchronous Operations.md
• Figuring out lifetime management #9: lifetime management
  Ownership.md probably sufficient

Things that use callbacks (Futures) instead of promises:
should be sufficiently covered in Asynchronous Operations.md

• Buffer mapping
• Error reporting
• Device loss
• Fence
  doesn't exist anymore

Other:

• WGPUBindGroupBindingDescriptor (no sum types in C)
  will get documented with Representation of GPUBindGroupLayoutEntry #438 / Representation of GPUBindGroupEntry #403
• How the regular part of webgpu.h relates the the WebGPU IDL
  State that webgpu.h has the same behavior as the JS spec #452
  but could use more docs still; tracked in:
  Please document the relationship between webgpu.idl and webgpu.yml #484
• Add support for null targets in WGPUFragmentState #160 How to make holes in WebGPU sparse arrays that are plain C arrays.

2024-11-27: updates from @kainino0x in italics

• All items in the "needs docs" label (regardless of whether open or closed)

[kainino0x]

I've created a new "needs docs" label which I'll try to add to everything that we're going to need to write docs/spec for.
https://github.com/webgpu-native/webgpu-headers/issues?q=label%3A%22needs+docs%22

[kainino0x]

I didn't go through the closed issues though. There may be some which still need documentation and should have the label added.

[kainino0x]

See discussion here #275 (comment) about having a "doc jam" to get the docs written

[kainino0x]

Apr 11 meeting:

• doc jam - how should we do this?
• KN: add links to spec in yaml?
  • pull text from it at codegen time? (but the names will differ)
  • or just generate links to the spec?
• Generator pulling from spec is worth exploring - from html
• Explore having the spec repo itself generate some parseable (e.g. json) documentation out of the spec, similar to what types generator does today — then use this for both typescript and C

[kainino0x]

We still want to fill out the docs for everything (see last comment).

The last item from the OP:

• How the regular part of webgpu.h relates the the WebGPU IDL

has a partial fix in #452, but ideally we should eventually write a doc that explains the patterns used to translate WebIDL to C.

However! I am going to call both of these things non-breaking for 1.0 and label this issue as such.