Clearer schema for ownership docs (webgpu-native#373)

* Clearer schema for ownership docs * also fix string doc
kainino0x · Oct 17, 2024 · 1430e17 · 1430e17
1 parent ea0ac14
commit 1430e17
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 64 deletions.
diff --git a/doc/articles/Strings.md b/doc/articles/Strings.md
@@ -6,7 +6,7 @@ Strings are represented using the \ref WGPUStringView struct:
 
 ## Nullable Input String {#NullableInputString}
 
-An input string where the null value may be treated separately from the 
+An input string where the null value may be treated separately from the empty string (e.g. to indicate the absence of a string, or to run some non-trivial defaulting algorithm).
 
 ## Non-Null Input String {#NonNullInputString}
 

diff --git a/gen/gen.go b/gen/gen.go
@@ -53,11 +53,12 @@ func (g *Generator) Gen(dst io.Writer) error {
 						sArg += argDoc
 					}
 
-					switch arg.OwnershipDoc {
-					case "with":
-						sArg += "\nThis parameter is @ref ReturnedWithOwnership."
-					case "without":
-						panic("invalid")
+					if arg.PassedWithOwnership != nil {
+						if *arg.PassedWithOwnership {
+							sArg += "\nThis parameter is @ref ReturnedWithOwnership."
+						} else {
+							panic("invalid")
+						}
 					}
 
 					sArg = strings.TrimSpace(sArg)
@@ -88,11 +89,12 @@ func (g *Generator) Gen(dst io.Writer) error {
 						sArg += argDoc
 					}
 
-					switch arg.OwnershipDoc {
-					case "with":
-						sArg += "\nThis parameter is @ref PassedWithOwnership."
-					case "without":
-						sArg += "\nThis parameter is @ref PassedWithoutOwnership."
+					if arg.PassedWithOwnership != nil {
+						if *arg.PassedWithOwnership {
+							sArg += "\nThis parameter is @ref PassedWithOwnership."
+						} else {
+							sArg += "\nThis parameter is @ref PassedWithoutOwnership."
+						}
 					}
 
 					sArg = strings.TrimSpace(sArg)
@@ -119,7 +121,7 @@ func (g *Generator) Gen(dst io.Writer) error {
 					s += "\n\nThis is an \\ref OutputString."
 				}
 
-				if member.OwnershipDoc != "" {
+				if member.PassedWithOwnership != nil {
 					panic("invalid")
 				}
 

diff --git a/gen/yml.go b/gen/yml.go
@@ -67,13 +67,13 @@ const (
 )
 
 type ParameterType struct {
-	Name         string      `yaml:"name"`
-	Doc          string      `yaml:"doc"`
-	Type         string      `yaml:"type"`
-	OwnershipDoc string      `yaml:"ownership_doc"`
-	Pointer      PointerType `yaml:"pointer"`
-	Optional     bool        `yaml:"optional"`
-	Namespace    string      `yaml:"namespace"`
+	Name                string      `yaml:"name"`
+	Doc                 string      `yaml:"doc"`
+	Type                string      `yaml:"type"`
+	PassedWithOwnership *bool       `yaml:"passed_with_ownership"`
+	Pointer             PointerType `yaml:"pointer"`
+	Optional            bool        `yaml:"optional"`
+	Namespace           string      `yaml:"namespace"`
 }
 
 type Callback struct {

diff --git a/schema.json b/schema.json
@@ -199,12 +199,9 @@
                             "$ref": "#/definitions/Type",
                             "description": "Return type of the function"
                         },
-                        "ownership": {
-                            "type": "string",
-                            "description": "Ownership of the value",
-                            "enum": [
-                                "with"
-                            ]
+                        "passed_with_ownership": {
+                            "type": "boolean",
+                            "description": "Whether the value is passed with ownership or without ownership"
                         },
                         "pointer": {
                             "$ref": "#/definitions/Pointer",