Move mainpage documentation to yml file (#458)

Author: eliemichel

gen/cheader.tmpl

@@ -1,21 +1,7 @@
 {{- MCommentN .Copyright 0}}
 
 /** @file */
-
-/**
- * \mainpage
- *
- * **Important:** *This documentation is a Work In Progress.*
- *
- * This is the home of WebGPU C API specification. We define here the standard
- * `webgpu.h` header that all implementations should provide.
- *
- * For all details where behavior is not otherwise specified, `webgpu.h` has
- * the same behavior as the WebGPU specification for JavaScript on the Web.
- * The WebIDL-based Web specification is mapped into C as faithfully (and
- * bidirectionally) as practical/possible.
- * The working draft of WebGPU can be found at <https://www.w3.org/TR/webgpu/>.
- */
+{{MCommentMainPage .Doc 0}}
 
 #ifndef {{.HeaderName | ConstantCase}}_H_
 #define {{.HeaderName | ConstantCase}}_H_

gen/gen.go

@@ -24,6 +24,12 @@ func (g *Generator) Gen(dst io.Writer) error {
 			"MComment":  func(v string, indent int) string { return Comment(v, CommentTypeMultiLine, indent, true) },
 			"SCommentN": func(v string, indent int) string { return Comment(v, CommentTypeSingleLine, indent, false) },
 			"MCommentN": func(v string, indent int) string { return Comment(v, CommentTypeMultiLine, indent, false) },
+			"MCommentMainPage": func(v string, indent int) string {
+				if v == "" || strings.TrimSpace(v) == "TODO" {
+					return ""
+				}
+				return Comment("\\mainpage\n\n"+strings.TrimSpace(v), CommentTypeMultiLine, indent, true)
+			},
 			"MCommentEnum": func(v string, indent int, prefix string, e Enum, entryIndex int) string {
 				if v == "" || strings.TrimSpace(v) == "TODO" {
 					return ""

gen/yml.go

@@ -10,6 +10,7 @@ import (
 type Yml struct {
 	Copyright  string `yaml:"copyright"`
 	Name       string `yaml:"name"`
+	Doc        string `yaml:"doc"`
 	EnumPrefix string `yaml:"enum_prefix"`
 
 	Constants []Constant `yaml:"constants"`

schema.json

@@ -258,6 +258,9 @@
             "pattern": "^0x[0-9]{4}$",
             "description": "The dedicated enum prefix for the implementation specific header to avoid collisions"
         },
+        "doc": {
+            "type": "string"
+        },
         "typedefs": {
             "type": "array",
             "items": {
@@ -514,6 +517,7 @@
         "copyright",
         "name",
         "enum_prefix",
+        "doc",
         "constants",
         "typedefs",
         "enums",

webgpu.yml

@@ -4,6 +4,17 @@ copyright: |
   SPDX-License-Identifier: BSD-3-Clause
 name: webgpu
 enum_prefix: '0x0000'
+doc: |
+  **Important:** *This documentation is a Work In Progress.*
+
+  This is the home of WebGPU C API specification. We define here the standard
+  `webgpu.h` header that all implementations should provide.
+
+  For all details where behavior is not otherwise specified, `webgpu.h` has
+  the same behavior as the WebGPU specification for JavaScript on the Web.
+  The WebIDL-based Web specification is mapped into C as faithfully (and
+  bidirectionally) as practical/possible.
+  The working draft of WebGPU can be found at <https://www.w3.org/TR/webgpu/>.
 constants:
   - name: array_layer_count_undefined
     value: uint32_max