From c6485a39eb93611a70e70d92237003369d10e368 Mon Sep 17 00:00:00 2001 From: dan sinclair Date: Sun, 11 Sep 2022 11:25:22 -0400 Subject: [PATCH] Add BufferBindingType docs. This CL adds documentation for the `buffer binding type` enumeration. The ability to link to the WGSL spec was added as well without having to provide the full spec URL. Issue #20 --- scripts/api_doc_generator.rb | 31 +++++++++++++++++-------------- src/api.yaml | 20 +++++++++++++++++++- 2 files changed, 36 insertions(+), 15 deletions(-) diff --git a/scripts/api_doc_generator.rb b/scripts/api_doc_generator.rb index 31ab544..63f7c17 100755 --- a/scripts/api_doc_generator.rb +++ b/scripts/api_doc_generator.rb @@ -8,6 +8,7 @@ API_YAML = File.join(BASE_DIR, "src", "api.yaml") WEBGPU_URL = "https://webgpu.dev" +WGSL_URL = "https://webgpu.dev/wgsl/" data = JSON.parse(File.open(DAWN_JSON).read) ['_comment', '_doc', '_metadata'].each { |n| data.delete(n) } @@ -107,9 +108,9 @@ def gen_table(f, lang, name, values, info, &block) f.puts "" end -def gen_description_and_ref(f, info) +def gen_description_and_ref(f, lang, info) if !info["description"].nil? - f.puts info["description"] + f.puts substitute(lang, info["description"]) f.puts "" end @@ -246,6 +247,8 @@ def substitute(lang, str) end "[#{display_name}](##{gen_anchor(obj)}-#{method.CamelCase})" + elsif cmd =~ /wgsl\(([^\)]*)\)/ + "#{WGSL_URL}#{$1}" else if lang == "cpp" if cmd == 'null' @@ -319,7 +322,7 @@ def gen_cpp_enums(f) emit_type(f, 'enum') do |e, name, info| gen_linked_header(f, 'enum class', name, '', 3, 'enum') { |n| n.CamelCase } - gen_description_and_ref(f, info) + gen_description_and_ref(f, "cpp", info) gen_table(f, "cpp", name, e['values'], info['values']) { |n| n.CamelCase } end end @@ -334,7 +337,7 @@ def gen_cpp_bitmasks(f) emit_type(f, 'bitmask') do |b, name, info| gen_linked_header(f, 'enum class', name, '[bitmask]', 3, 'bitmask') { |n| n.CamelCase } - gen_description_and_ref(f, info) + gen_description_and_ref(f, "cpp", info) gen_table(f, "cpp", name, b['values'], info['values']) { |n| n.CamelCase } end end @@ -346,7 +349,7 @@ def gen_cpp_function(f) gen_linked_header(f, '', name, '', 3, 'function') { |n| n.CamelCase } emit_div_block(f, 'content') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "cpp", info) emit_div_block(f, 'signature') do f.write "#{gen_cpp_type_link(func['returns'])} #{name.CamelCase}" @@ -371,7 +374,7 @@ def gen_cpp_function_pointers(f) gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| n.CamelCase } emit_div_block(f, 'content') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "cpp", info) emit_div_block(f, 'signature') do f.write "void (*#{name.CamelCase})" @@ -444,7 +447,7 @@ def gen_cpp_classes(f) emit_div_block(f, 'content') do emit_div_block(f, 'description') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "cpp", info) end (klass['methods'] || []).sort { |a, b| a['name'] <=> b['name'] }.each do |method| @@ -454,7 +457,7 @@ def gen_cpp_classes(f) end method_info = (info['methods'] || {})[method['name']] || {} - gen_description_and_ref(f, method_info) + gen_description_and_ref(f, "cpp", method_info) emit_div_block(f, 'signature') do f.write "#{gen_cpp_type_link(method['returns'])} #{method['name'].CamelCase}" @@ -544,7 +547,7 @@ def gen_c_enums(f) emit_type(f, 'enum') do |e, name, info| gen_linked_header(f, 'enum', name, '', 3, 'enum') { |n| "WGPU#{n.CamelCase}" } - gen_description_and_ref(f, info) + gen_description_and_ref(f, "c", info) gen_table(f, "c", name, e['values'], info['values']) do |n| "WGPU#{name.CamelCase}_#{n.CamelCase}" end @@ -562,7 +565,7 @@ def gen_c_bitmasks(f) emit_type(f, 'bitmask') do |b, name, info| gen_linked_header(f, 'enum', name, '[bitmask]', 2, 'bitmask') { |n| "WGPU#{n.CamelCase}" } - gen_description_and_ref(f, info) + gen_description_and_ref(f, "c", info) gen_table(f, "c", name, b['values'], info['values']) do |n| "WGPU#{name.CamelCase}_#{n.CamelCase}" end @@ -578,7 +581,7 @@ def gen_c_function(f) gen_linked_header(f, '', name, '', 3, 'function') { |n| "wgpu#{n.CamelCase}" } emit_div_block(f, 'content') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "c", info) emit_div_block(f, 'signature') do f.write "#{gen_c_type_link(func['returns'])} wgpu#{name.CamelCase}" @@ -603,7 +606,7 @@ def gen_c_function_pointers(f) gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| "WGPU#{n.CamelCase}" } emit_div_block(f, 'content') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "c", info) emit_div_block(f, 'signature') do f.write "void (*WGPU#{name.CamelCase})" @@ -668,7 +671,7 @@ def gen_c_objects(f) emit_div_block(f, 'content') do emit_div_block(f, 'description') do - gen_description_and_ref(f, info) + gen_description_and_ref(f, "c", info) end methods = (klass['methods'] || []) @@ -693,7 +696,7 @@ def gen_c_objects(f) end method_info = (info['methods'] || {})[method['name']] || {} - gen_description_and_ref(f, method_info) + gen_description_and_ref(f, "c", method_info) emit_div_block(f, 'signature') do f.write "#{gen_c_type_link(method['returns'])} #{to_method_name.call(method['name'])}" diff --git a/src/api.yaml b/src/api.yaml index 94e19ea..2774288 100644 --- a/src/api.yaml +++ b/src/api.yaml @@ -152,6 +152,24 @@ enum: Takes the maximum of the source and destination.
`max(RGBA_src, RGBA_dst)` + buffer binding type: + description: > + Describes the address space and access mode for the buffer binding. The + value used must match up to the + [address space](%% wgsl(#address-space) %%) and + [access mode](%% wgsl(#memory-access-mode) %%) set + in the corresponding WGSL shader. + ref: + name: GPUBufferBindingType + anchor: "#enumdef-gpubufferbindingtype" + values: + undefined: Undefined binding. + uniform: Binding in the `uniform` address space. + storage: > + Binding in the `storage` address space with `read-write` access mode. + read only storage: > + Binding in the `storage` address space with `read` access mode. + bitmask: texture usage: description: Determine how a GPUTexture maybe be used after creation. @@ -187,7 +205,7 @@ function: returns: proc: > The %% proc %% function pointer if it exists, - %% null %% otherwise. + `%% null %%` otherwise. args: device: The %% device %% to retrieve the proc for proc name: The name of the pointer to retrieve