Improve sentinel values documentation (#440)

doc/articles/SentinelValues.md

@@ -1,6 +1,6 @@
 # Sentinel Values {#SentinelValues}
 
-## Undefined
+## Undefined and Null
 
 Since WebGPU is defined first as a JavaScript API, it uses the JavaScript value
 `undefined` in many places to indicate the lack of a value.
@@ -14,7 +14,8 @@ It may also be used in functions/methods. For example, `GPUBuffer`'s
 can be called equivalently as `b.getMappedRange()`, `b.getMappedRange(0)`,
 `b.getMappedRange(undefined)`, or `b.getMappedRange(undefined, undefined)`.
 
-To represent `undefined` in C, `webgpu.h` uses `*_UNDEFINED` sentinel numeric values
+To represent `undefined` in C, `webgpu.h` uses `NULL` where possible (anything
+behind a pointer, including objects), `*_UNDEFINED` sentinel numeric values
 (generally `UINT32_MAX`, etc.) and `*_Undefined` enum values (generally `0`).
 
 The place that uses the type will define what to do with an undefined value.
@@ -26,13 +27,19 @@ It may be:
   (usually this is either a special value or it has more complex defaulting,
   for example depending on other values).
 
-## Other sentinel values
-
-Undefined values are also be used in C-specific ways in place of WebIDL's
-more flexible typing:
-
-- \ref WGPUVertexStepMode_VertexBufferNotUsed
-- \ref WGPUBufferBindingType_BindingNotUsed
-- \ref WGPUSamplerBindingType_BindingNotUsed
-- \ref WGPUTextureSampleType_BindingNotUsed
-- \ref WGPUStorageTextureAccess_BindingNotUsed
+## C-Specific Sentinel Values
+
+Undefined and null values are also used in C-specific ways in place of
+WebIDL's more flexible typing:
+
+- \ref WGPUStringView has a special null value
+- \ref WGPUFuture has a special null value
+- Special cases to indicate the parent struct is null, avoiding extra layers of
+  pointers just for nullability:
+    - \ref WGPUVertexBufferLayout::stepMode = \ref WGPUVertexStepMode_VertexBufferNotUsed
+    - \ref WGPUBufferBindingLayout::type = \ref WGPUBufferBindingType_BindingNotUsed
+    - \ref WGPUSamplerBindingLayout::type = \ref WGPUSamplerBindingType_BindingNotUsed
+    - \ref WGPUTextureBindingLayout::sampleType = \ref WGPUTextureSampleType_BindingNotUsed
+    - \ref WGPUStorageTextureBindingLayout::access = \ref WGPUStorageTextureAccess_BindingNotUsed
+    - \ref WGPURenderPassColorAttachment::view = `NULL`
+    - \ref WGPUColorTargetState::format = \ref WGPUTextureFormat_Undefined

webgpu.h

@@ -3668,6 +3668,9 @@ typedef struct WGPUInstanceDescriptor {
 typedef struct WGPURenderPassColorAttachment {
     WGPUChainedStruct const * nextInChain;
     /**
+     * If `NULL`, indicates a hole in the parent
+     * @ref WGPURenderPassDescriptor::colorAttachments array.
+     *
      * The `INIT` macro sets this to `NULL`.
      */
     WGPU_NULLABLE WGPUTextureView view;

webgpu.yml

@@ -2374,7 +2374,8 @@ structs:
     members:
       - name: view
         doc: |
-          TODO
+          If `NULL`, indicates a hole in the parent
+          @ref WGPURenderPassDescriptor::colorAttachments array.
         type: object.texture_view
         optional: true
       - name: depth_slice