From 7144195a8d8eae0476030d8b90abed412a886e6d Mon Sep 17 00:00:00 2001
From: dan sinclair <dj2@everburning.com>
Date: Sat, 10 Sep 2022 13:45:10 -0400
Subject: [PATCH 1/4] Style and linking cleanup for API documentation.

This CL updates the API document styles. The header links are also
updated to work a bit better, each method has a header ID which can be
used to link from other parts of the text.

Issue #10
---
 docs/_includes/anchor_links.html |   6 +-
 docs/_sass/main.scss             |  78 ++++++---
 scripts/api_doc_generator.rb     | 269 +++++++++++++++++--------------
 3 files changed, 205 insertions(+), 148 deletions(-)

diff --git a/docs/_includes/anchor_links.html b/docs/_includes/anchor_links.html
index 8f0f510..880b9d2 100644
--- a/docs/_includes/anchor_links.html
+++ b/docs/_includes/anchor_links.html
@@ -4,9 +4,9 @@
   var anchor = document.createElement("a");
   anchor.className = "header-link";
   anchor.href = "#" + header.id;
+  anchor.innerHTML = "&nearhk;"
 
-  header.parentNode.insertBefore(anchor, header);
-  anchor.appendChild(header);
+  header.appendChild(anchor);
 };
 
 var link_anchors = function(level, parent) {
@@ -23,7 +23,7 @@
 
 document.addEventListener('DOMContentLoaded', () => {
   var main = document.getElementsByClassName("main")[0];
-  for(var i = 2; i < 4; i++) {
+  for(var i = 2; i < 5; i++) {
     link_anchors(i, main);
   }
 });
diff --git a/docs/_sass/main.scss b/docs/_sass/main.scss
index 8f27960..6da17f4 100644
--- a/docs/_sass/main.scss
+++ b/docs/_sass/main.scss
@@ -56,7 +56,6 @@ header {
 
 table {
   border-collapse: collapse;
-  margin: 25px 0;
   font-size: 0.9em;
   box-shadow: 0 0 20px $shadow-colour;
 
@@ -89,14 +88,8 @@ table {
 }
 
 .function {
-  box-shadow: 0 0 20px $shadow-colour;
-  margin-bottom: 1em;
-
-  .header-link {
-    text-decoration: none;
-  }
-
   h3 {
+    margin: 0;
     background-color: $table-border;
     color: #fff;
     padding: 2px;
@@ -105,40 +98,79 @@ table {
   }
 
   .content {
-    padding: 5px;
-
-    h4 { margin-bottom: 0; }
+    padding: .5em .5em;
 
-    ul {
-      list-style-type: none;
-      margin: 0;
-      padding: 1em;
+    p {
+      margin-top: 0;
     }
   }
 }
 
+.function, .method {
+  box-shadow: 0 0 20px $shadow-colour;
+  margin: .5em 0;
+
+  h4 {
+    margin: 0;
+    padding: 0;
+    border-bottom: 1px solid $shadow-colour;
+  }
+  h5 { margin-bottom: 0; }
+
+  ul {
+    list-style-type: none;
+    margin: 0;
+    margin-top: 5px;
+    padding: 0;
+  }
+}
+
 .object {
+  margin-top: 1em;
+
   .header-link { text-decoration: none; }
 
   h3 {
     background-color: $table-border;
     color: #fff;
+    margin-top: 0;
     padding: 2px;
     border-top-left-radius: 5px;
     border-top-right-radius: 5px;
   }
 
-  .method {
-    box-shadow: 0 0 20px $shadow-colour;
-    margin: .5em 0;
+  .content {
+    border: 1px solid $shadow-colour;
     padding: .5em .5em;
 
-    h4 { margin-bottom: 0; }
+    .method {
+      padding: .5em .5em;
+    }
 
-    ul {
-      list-style-type: none;
-      margin: 0;
-      padding: 1em;
+    p {
+      margin-top: 0;
     }
   }
 }
+
+.header-link {
+  margin-left: .5em;
+}
+
+.structure {
+  border-bottom: 2px solid $shadow-colour;
+  padding-bottom: 1em;
+
+  ul {
+    margin: 0;
+  }
+  h5 {
+    margin-bottom: 0;
+  }
+}
+
+.enum {
+  p {
+    margin-top: .25em;
+  }
+}
diff --git a/scripts/api_doc_generator.rb b/scripts/api_doc_generator.rb
index 1d06693..3eba642 100755
--- a/scripts/api_doc_generator.rb
+++ b/scripts/api_doc_generator.rb
@@ -86,14 +86,23 @@ def gen_header(f, name, length = 2)
   f.puts ""
 end
 
-def gen_table(f, name, values, info, &block)
+def gen_linked_header(f, prefix, name, suffix, lvl, id_kind, &block)
+  prefix = "#{prefix} " unless prefix.empty?
+  suffix = " #{suffix}" unless suffix.empty?
+
+  gen_header(f,
+    "#{prefix}#{block.call(name)}#{suffix} {##{id_kind}-#{name.CamelCase}}",
+    lvl)
+end
+
+def gen_table(f, lang, name, values, info, &block)
   f.puts ""
   f.puts "| Value | Description |"
   f.puts "|:------|:------------|"
   values.each do |v|
     vn = v['name']
     puts "Unable to find value for #{name} :: #{vn}" unless info.has_key?(vn)
-    f.puts "| `#{block.call(vn)}` | #{info[vn].strip} |"
+    f.puts "| `#{block.call(vn)}` | #{substitute(lang, info[vn].strip)} |"
   end
   f.puts ""
 end
@@ -125,13 +134,17 @@ def get_info(type, name)
   info
 end
 
+def gen_anchor(type)
+  "#{$kinds[type]}-#{type.CamelCase}"
+end
+
 def gen_type_link(prefix, page, type)
   return "void" if type.nil?
 
   if $native_types.has_key?(type)
     type
   else
-    "[#{prefix}#{type.CamelCase}]({{ '#{page}##{$kinds[type]}-#{type.CamelCase}' | relative_url }})"
+    "[#{prefix}#{type.CamelCase}]({{ '#{page}##{gen_anchor(type)}' | relative_url }})"
   end
 end
 
@@ -143,12 +156,15 @@ def gen_c_type_link(type)
   gen_type_link("WGPU", "/api/c.html", type)
 end
 
-def emit_type(type, &block)
+def emit_type(f, type, &block)
   order_by_name(@categories[type]).each do |k|
     name = k['name']
 
     info = get_info(type, name)
-    block.call(k, name, info)
+
+    emit_div_block(f, type) do
+      block.call(k, name, info)
+    end
   end
 end
 
@@ -163,19 +179,13 @@ def emit_div_block(f, name, &block)
 def emit_params(f, args, &block)
   f.write "("
   args.each_with_index do |a, idx|
-    f.write ", " if idx > 0
+    f.write "," if idx > 0
+    f.write "<br>&nbsp; &nbsp;&nbsp;"
     f.write block.call(a)
   end
   f.puts ")"
 end
 
-def gen_linked_header(f, prefix, name, suffix, id_kind, &block)
-  prefix = "#{prefix} " unless prefix.empty?
-  suffix = " #{suffix}" unless suffix.empty?
-
-  gen_header(f, "#{prefix}#{block.call(name.CamelCase)}#{suffix} {##{id_kind}-#{name.CamelCase}}", 3)
-end
-
 def gen_list(f, list, &block)
   list.each do |name|
     f.puts " * #{block.call(name)}"
@@ -254,7 +264,7 @@ def emit_value_or_warning(f, lang, info, value, name, default="")
 def emit_args(f, lang, src_name, args, info)
   return if args.nil? || args.empty?
 
-  gen_header(f, "Arguments", 4)
+  gen_header(f, "Arguments", 5)
   args.each do |arg|
     arg_name = arg['name']
 
@@ -294,10 +304,10 @@ def gen_cpp_constants(f)
 def gen_cpp_enums(f)
   gen_header(f, "Enums")
 
-  emit_type('enum') do |e, name, info|
-    gen_linked_header(f, 'enum class', name, '', 'enum') { |n| n }
+  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_table(f, name, e['values'], info['values']) { |n| n.CamelCase }
+    gen_table(f, "cpp", name, e['values'], info['values']) { |n| n.CamelCase }
   end
 end
 
@@ -309,35 +319,33 @@ def gen_cpp_bitmasks(f)
     operators in order to use them as bitmasks.
     HERE
 
-  emit_type('bitmask') do |b, name, info|
-    gen_linked_header(f, 'enum class', name, '[bitmask]', 'bitmask') { |n| n }
+  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_table(f, name, b['values'], info['values']) { |n| n.CamelCase }
+    gen_table(f, "cpp", name, b['values'], info['values']) { |n| n.CamelCase }
   end
 end
 
 def gen_cpp_function(f)
   gen_header(f, "Functions")
 
-  emit_type('function') do |func, name, info|
-    emit_div_block(f, 'function') do
-      gen_linked_header(f, '', name, '', 'function') { |n| n }
+  emit_type(f, 'function') do |func, name, info|
+    gen_linked_header(f, '', name, '', 3, 'function') { |n| n.CamelCase }
 
-      emit_div_block(f, 'content') do
-        gen_description_and_ref(f, info)
+    emit_div_block(f, 'content') do
+      gen_description_and_ref(f, info)
 
-        emit_div_block(f, 'signature') do
-          f.write "#{gen_cpp_type_link(func['returns'])} #{name.CamelCase}"
-          emit_params(f, func['args']) { |p| gen_cpp_member(p) }
-        end
+      emit_div_block(f, 'signature') do
+        f.write "#{gen_cpp_type_link(func['returns'])} #{name.CamelCase}"
+        emit_params(f, func['args']) { |p| gen_cpp_member(p) }
+      end
 
-        gen_header(f, 'Returns', 4)
-        emit_value_or_warning(f, "cpp", info['returns'], func['returns'], func['name'])
-        f.puts ""
-        f.puts ""
+      gen_header(f, 'Returns', 5)
+      emit_value_or_warning(f, "cpp", info['returns'], func['returns'], func['name'])
+      f.puts ""
+      f.puts ""
 
-        emit_args(f, "cpp", func['name'], func['args'], info)
-      end
+      emit_args(f, "cpp", func['name'], func['args'], info)
     end
   end
 end
@@ -345,9 +353,9 @@ def gen_cpp_function(f)
 def gen_cpp_function_pointers(f)
   gen_header(f, "Function Pointers")
 
-  emit_type('function pointer') do |func, name, info|
+  emit_type(f, 'function pointer') do |func, name, info|
     emit_div_block(f, 'function') do
-      gen_linked_header(f, '', name, '', 'function-pointer') { |n| n }
+      gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| n.CamelCase }
 
       emit_div_block(f, 'content') do
         gen_description_and_ref(f, info)
@@ -366,8 +374,8 @@ def gen_cpp_function_pointers(f)
 def gen_cpp_structures(f)
   gen_header(f, "Structures")
 
-  emit_type('structure') do |struct, name, info|
-    gen_linked_header(f, 'struct', name, '', 'structure') { |n| n }
+  emit_type(f, 'structure') do |struct, name, info|
+    gen_linked_header(f, 'struct', name, '', 3, 'structure') { |n| n.CamelCase }
 
     if !struct['members'].empty? || ['in', 'out'].include?(struct['extensible']) ||
           ['in', 'out'].include?(struct['chained'])
@@ -403,12 +411,12 @@ def gen_cpp_structures(f)
     end
 
     if !$chain_in[name].nil?
-      gen_header(f, 'Chainable Structures', 4)
+      gen_header(f, 'Chainable Structures', 5)
       gen_list(f, $chain_in[name]) { |n| gen_cpp_type_link(n) }
     end
 
     if !$chain_in_parents[name].nil?
-      gen_header(f, 'Chain Parent Structures', 4)
+      gen_header(f, 'Chain Parent Structures', 5)
       gen_list(f, $chain_in_parents[name]) { |n| gen_cpp_type_link(n) }
     end
   end
@@ -417,31 +425,39 @@ def gen_cpp_structures(f)
 def gen_cpp_classes(f)
   gen_header(f, "Classes")
 
-  emit_type('object') do |klass, name, info|
+  emit_type(f, 'object') do |klass, name, info|
     emit_div_block(f, 'object') do
-      gen_linked_header(f, 'class', name, '', 'class') { |n| n }
-      gen_description_and_ref(f, info)
-
-      (klass['methods'] || []).sort { |a, b| a['name'] <=> b['name'] }.each do |method|
-        emit_div_block(f, 'method') do
-
-          method_info = (info['methods'] || {})[method['name']] || {}
-          gen_description_and_ref(f, method_info)
+      gen_linked_header(f, 'class', name, '', 3, 'class') { |n| n.CamelCase }
 
-          emit_div_block(f, 'signature') do
-            f.write "#{gen_cpp_type_link(method['returns'])} #{method['name'].CamelCase}"
-            emit_params(f, method['args'] || []) { |p| gen_cpp_member(p) }
-            f.puts ""
-          end
+      emit_div_block(f, 'content') do
+        emit_div_block(f, 'description') do
+          gen_description_and_ref(f, info)
+        end
 
-          if !method['returns'].nil? && method['returns'] != 'void'
-            gen_header(f, "Returns", 4)
-            emit_value_or_warning(f, "cpp", method_info['returns'],
-                    method['returns'], method['name'])
-            f.puts ""
+        (klass['methods'] || []).sort { |a, b| a['name'] <=> b['name'] }.each do |method|
+          emit_div_block(f, 'method') do
+            gen_linked_header(f, '', method['name'], '', 4, "#{gen_anchor(name)}") do |n|
+              n.CamelCase
+            end
+
+            method_info = (info['methods'] || {})[method['name']] || {}
+            gen_description_and_ref(f, method_info)
+
+            emit_div_block(f, 'signature') do
+              f.write "#{gen_cpp_type_link(method['returns'])} #{method['name'].CamelCase}"
+              emit_params(f, method['args'] || []) { |p| gen_cpp_member(p) }
+              f.puts ""
+            end
+
+            if !method['returns'].nil? && method['returns'] != 'void'
+              gen_header(f, "Returns", 5)
+              emit_value_or_warning(f, "cpp", method_info['returns'],
+                      method['returns'], method['name'])
+              f.puts ""
+            end
+
+            emit_args(f, "cpp", method['name'], method['args'], method_info)
           end
-
-          emit_args(f, "cpp", method['name'], method['args'], method_info)
         end
       end
     end
@@ -513,10 +529,10 @@ def gen_c_constants(f)
 def gen_c_enums(f)
   gen_header(f, "Enums")
 
-  emit_type('enum') do |e, name, info|
-    gen_linked_header(f, 'enum', name, '', 'enum') { |n| "WGPU#{n}" }
+  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_table(f, name, e['values'], info['values']) do |n|
+    gen_table(f, "c", name, e['values'], info['values']) do |n|
       "WGPU#{name.CamelCase}_#{n.CamelCase}"
     end
   end
@@ -531,10 +547,10 @@ def gen_c_bitmasks(f)
     signatures.
     HERE
 
-  emit_type('bitmask') do |b, name, info|
-    gen_linked_header(f, 'enum', name, '[bitmask]', 'bitmask') { |n| "WGPU#{n}" }
+  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_table(f, name, b['values'], info['values']) do |n|
+    gen_table(f, "c", name, b['values'], info['values']) do |n|
       "WGPU#{name.CamelCase}_#{n.CamelCase}"
     end
     f.puts "`typedef WGPUFlags WGPU#{name.CamelCase}Flags`"
@@ -545,25 +561,23 @@ def gen_c_bitmasks(f)
 def gen_c_function(f)
   gen_header(f, "Functions")
 
-  emit_type('function') do |func, name, info|
-    emit_div_block(f, 'function') do
-      gen_linked_header(f, '', name, '', 'function') { |n| "wgpu#{n}" }
+  emit_type(f, 'function') do |func, name, info|
+    gen_linked_header(f, '', name, '', 3, 'function') { |n| "wgpu#{n.CamelCase}" }
 
-      emit_div_block(f, 'content') do
-        gen_description_and_ref(f, info)
+    emit_div_block(f, 'content') do
+      gen_description_and_ref(f, info)
 
-        emit_div_block(f, 'signature') do
-          f.write "#{gen_c_type_link(func['returns'])} wgpu#{name.CamelCase}"
-          emit_params(f, func['args']) { |p| gen_c_member(p) }
-        end
+      emit_div_block(f, 'signature') do
+        f.write "#{gen_c_type_link(func['returns'])} wgpu#{name.CamelCase}"
+        emit_params(f, func['args']) { |p| gen_c_member(p) }
+      end
 
-        gen_header(f, 'Returns', 4)
-        emit_value_or_warning(f, "c", info['returns'], func['returns'], func['name'])
-        f.puts ""
-        f.puts ""
+      gen_header(f, 'Returns', 5)
+      emit_value_or_warning(f, "c", info['returns'], func['returns'], func['name'])
+      f.puts ""
+      f.puts ""
 
-        emit_args(f, "c", func['name'], func['args'], info)
-      end
+      emit_args(f, "c", func['name'], func['args'], info)
     end
   end
 end
@@ -571,9 +585,9 @@ def gen_c_function(f)
 def gen_c_function_pointers(f)
   gen_header(f, "Function Pointers")
 
-  emit_type('function pointer') do |func, name, info|
+  emit_type(f, 'function pointer') do |func, name, info|
     emit_div_block(f, 'function') do
-      gen_linked_header(f, '', name, '', 'function-pointer') { |n| "WGPU#{n}" }
+      gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| "WGPU#{n.CamelCase}" }
 
       emit_div_block(f, 'content') do
         gen_description_and_ref(f, info)
@@ -592,8 +606,8 @@ def gen_c_function_pointers(f)
 def gen_c_structures(f)
   gen_header(f, "Structures")
 
-  emit_type('structure') do |struct, name, info|
-    gen_linked_header(f, 'struct', name, '', 'structure') { |n| "WGPU#{n}" }
+  emit_type(f, 'structure') do |struct, name, info|
+    gen_linked_header(f, 'struct', name, '', 3, 'structure') { |n| "WGPU#{n.CamelCase}" }
 
     if !struct['members'].empty? || ['in', 'out'].include?(struct['extensible']) ||
           ['in', 'out'].include?(struct['chained'])
@@ -621,12 +635,12 @@ def gen_c_structures(f)
     end
 
     if !$chain_in[name].nil?
-      gen_header(f, 'Chainable Structures', 4)
+      gen_header(f, 'Chainable Structures', 5)
       gen_list(f, $chain_in[name]) { |n| gen_c_type_link(n) }
     end
 
     if !$chain_in_parents[name].nil?
-      gen_header(f, 'Chain Parent Structures', 4)
+      gen_header(f, 'Chain Parent Structures', 5)
       gen_list(f, $chain_in_parents[name]) { |n| gen_c_type_link(n) }
     end
   end
@@ -635,43 +649,54 @@ def gen_c_structures(f)
 def gen_c_objects(f)
   gen_header(f, "Methods")
 
-  emit_type('object') do |klass, name, info|
+  emit_type(f, 'object') do |klass, name, info|
     emit_div_block(f, 'object') do
-      gen_linked_header(f, 'Methods of', name, '', 'class') { |n| "WGPU#{n}" }
-      gen_description_and_ref(f, info)
+      gen_linked_header(f, 'Methods of', name, '', 3, 'class') { |n| "WGPU#{n.CamelCase}" }
 
-      methods = (klass['methods'] || [])
-      methods.push({
-        "name" => "reference"
-      })
-      methods.push({
-        "name" => "release"
-      })
-
-      methods.sort { |a, b| a['name'] <=> b['name'] }.each do |method|
-        emit_div_block(f, 'method') do
-          args = method['args'] || []
-          args.unshift({
-            "name" => klass['name'],
-            "type" => klass['name']
-          })
-
-          method_info = (info['methods'] || {})[method['name']] || {}
-          gen_description_and_ref(f, method_info)
-
-          emit_div_block(f, 'signature') do
-            f.write "#{gen_c_type_link(method['returns'])} wgpu#{klass['name'].CamelCase}#{method['name'].CamelCase}"
-            emit_params(f, args) { |p| gen_c_member(p) }
-            f.puts ""
-          end
+      emit_div_block(f, 'content') do
+        emit_div_block(f, 'description') do
+          gen_description_and_ref(f, info)
+        end
 
-          if !method['returns'].nil? && method['returns'] != 'void'
-            gen_header(f, "Returns", 4)
-            emit_value_or_warning(f, "c", method_info['returns'], method['returns'], method['name'])
-            f.puts ""
+        methods = (klass['methods'] || [])
+        methods.push({
+          "name" => "reference"
+        })
+        methods.push({
+          "name" => "release"
+        })
+
+        methods.sort { |a, b| a['name'] <=> b['name'] }.each do |method|
+          emit_div_block(f, 'method') do
+            args = method['args'] || []
+            args.unshift({
+              "name" => klass['name'],
+              "type" => klass['name']
+            })
+
+            to_method_name = lambda { |n| "wgpu#{klass['name'].CamelCase}#{n.CamelCase}" }
+            gen_linked_header(f, '', method['name'], '', 4, "#{gen_anchor(name)}") do |n|
+                to_method_name.call(n)
+            end
+
+            method_info = (info['methods'] || {})[method['name']] || {}
+            gen_description_and_ref(f, method_info)
+
+            emit_div_block(f, 'signature') do
+              f.write "#{gen_c_type_link(method['returns'])} #{to_method_name.call(method['name'])}"
+              emit_params(f, args) { |p| gen_c_member(p) }
+              f.puts ""
+            end
+
+            if !method['returns'].nil? && method['returns'] != 'void'
+              gen_header(f, "Returns", 5)
+              emit_value_or_warning(
+                  f, "c", method_info['returns'], method['returns'], method['name'])
+              f.puts ""
+            end
+
+            emit_args(f, "c", method['name'], args, method_info)
           end
-
-          emit_args(f, "c", method['name'], args, method_info)
         end
       end
     end

From 980c29df01808c2b085d21633d0a55322cdb3cee Mon Sep 17 00:00:00 2001
From: dan sinclair <dj2@everburning.com>
Date: Sat, 10 Sep 2022 12:15:42 -0400
Subject: [PATCH 2/4] Add BlendFactor documentation.

This CL adds documentation for the blend factor enum values.

Issue #20
---
 src/api.yaml | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/src/api.yaml b/src/api.yaml
index 9c97690..3a5f433 100644
--- a/src/api.yaml
+++ b/src/api.yaml
@@ -77,6 +77,58 @@ enum:
       openGL: The OpenGL backend
       openGLES: The OpenGL ES backend
 
+  blend factor:
+    description: >
+      Determines how a blend factor is calculated. This factor will be combined
+      with the original color based on the selected blend operation.
+    ref:
+      name: GPUBlendFactor
+      anchor: '#enumdef-gpublendfactor'
+    values:
+      zero: >
+        Factor is set to zero.<br>
+        `(0, 0, 0, 0)`
+      one: >
+        Factor is set to one. <br>
+        `(1, 1, 1, 1)`
+      src: >
+        Factor is set to the source values. <br>
+        `(R_src, G_src, B_src, A_src)`
+      one minus src: >
+        Factor is set to one minus source value. <br>
+        `(1 - R_src, 1 - G_src, 1 - B_src, 1 - A_src)`
+      src alpha: >
+        Factor is set to the source alpha value. <br>
+        `(A_src, A_src, A_src, A_src)`
+      src alpha saturated: >
+        Factor is set to the source alpha value. <br>
+        `(A_src, A_src, A_src, A_src)`
+      one minus src alpha: >
+        Factor is set to one minus the source alpha value. <br>
+        `(1 - A_src, 1 - A_src, 1 - A_src, 1 - A_src)`
+      dst: >
+       Factor is set to the destination value.<br>
+       `(R_dst, G_dst, B_dst, A_dst)`
+      one minus dst: >
+        Factor is set to one minus destination value. <br>
+        `(1 - R_dst, 1 - G_dst, 1 - B_dst, 1 - A_dst)`
+      dst alpha: >
+        Factor is set to the destinatinon alpha value. <br>
+        `(A_dst, A_dst, A_dst, A_dst)`
+      one minus dst alpha: >
+        Factor is set to one minus the destionation alpha value. <br>
+        `(1 - A_dst, 1 - A_dst, 1 - A_dst, 1 - A_dst)`
+      constant: >
+        Factor is set to the constant value.
+        (See %% method(render pass encoder, set blend constant) %%
+        for setting of the constant value.)<br>
+        `(R_const, G_const, B_const, A_const)`
+      one minus constant: >
+        Factor is set to one minus the constant value.
+        (See %% method(render pass encoder, set blend constant) %%
+        for setting of the constant value.)<br>
+        `(1 - R_const, 1 - G_const, 1 - B_const, 1 - A_const)`
+
 bitmask:
   texture usage:
     description: Determine how a GPUTexture maybe be used after creation.

From e34d5ffea563fa14cbe05446c446920e76ded369 Mon Sep 17 00:00:00 2001
From: dan sinclair <dj2@everburning.com>
Date: Sat, 10 Sep 2022 14:01:25 -0400
Subject: [PATCH 3/4] Add substitute for method names

---
 scripts/api_doc_generator.rb | 27 ++++++++++++++++++++-------
 src/api.yaml                 |  4 ++--
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/scripts/api_doc_generator.rb b/scripts/api_doc_generator.rb
index 3eba642..31ab544 100755
--- a/scripts/api_doc_generator.rb
+++ b/scripts/api_doc_generator.rb
@@ -235,17 +235,30 @@ def substitute(lang, str)
   str.gsub(/%%(.*?)%%/) do |m|
     cmd = $1.strip!
 
-    if lang == "cpp"
-      if cmd == 'null'
-        "nullptr"
+    if cmd =~ /method\(([^,]*),\s+([^\)]*)\)/
+      obj = $1
+      method = $2
+
+      display_name = if lang == "cpp"
+        "#{obj.CamelCase}::#{method.CamelCase}"
       else
-        gen_cpp_type_link(cmd)
+        "wgpu#{obj.CamelCase}#{method.CamelCase}"
       end
+
+      "[#{display_name}](##{gen_anchor(obj)}-#{method.CamelCase})"
     else
-      if cmd == 'null'
-        "NULL"
+      if lang == "cpp"
+        if cmd == 'null'
+          "nullptr"
+        else
+          gen_cpp_type_link(cmd)
+        end
       else
-        gen_c_type_link(cmd)
+        if cmd == 'null'
+          "NULL"
+        else
+          gen_c_type_link(cmd)
+        end
       end
     end
   end
diff --git a/src/api.yaml b/src/api.yaml
index 3a5f433..8f9b9a5 100644
--- a/src/api.yaml
+++ b/src/api.yaml
@@ -119,12 +119,12 @@ enum:
         Factor is set to one minus the destionation alpha value. <br>
         `(1 - A_dst, 1 - A_dst, 1 - A_dst, 1 - A_dst)`
       constant: >
-        Factor is set to the constant value.
+        Factor is set to the constant value.<br>
         (See %% method(render pass encoder, set blend constant) %%
         for setting of the constant value.)<br>
         `(R_const, G_const, B_const, A_const)`
       one minus constant: >
-        Factor is set to one minus the constant value.
+        Factor is set to one minus the constant value.<br>
         (See %% method(render pass encoder, set blend constant) %%
         for setting of the constant value.)<br>
         `(1 - R_const, 1 - G_const, 1 - B_const, 1 - A_const)`

From d9fdd848a2de8435d43d20254169aa2d94d0d4f5 Mon Sep 17 00:00:00 2001
From: dan sinclair <dj2@everburning.com>
Date: Sat, 10 Sep 2022 15:20:38 -0400
Subject: [PATCH 4/4] Add `blend operation` enum documentation.

This CL documents the `blend operation` enumeration.

Issue #20
---
 src/api.yaml | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/api.yaml b/src/api.yaml
index 8f9b9a5..94e19ea 100644
--- a/src/api.yaml
+++ b/src/api.yaml
@@ -129,6 +129,29 @@ enum:
         for setting of the constant value.)<br>
         `(1 - R_const, 1 - G_const, 1 - B_const, 1 - A_const)`
 
+  blend operation:
+    description: >
+      The algorithm used to blend source and destination colors.
+    ref:
+      name: GPUBlendOperation
+      anchor: "#enumdef-gpublendoperation"
+    values:
+      add: >
+        Adds the scaled source and scaled destination together.<br>
+        `(RGBA_src` &times; `RGBA_src_factor) + (RGBA_dst` &times; `RGBA_dst_factor)`
+      subtract: >
+        Subtracts the scaled destination from the scaled source.<br>
+        `(RGBA_src` &times; `RGBA_src_factor) - (RGBA_dst` &times; `RGBA_dst_factor)`
+      reverse subtract: >
+        Subtracts the scaled source from the scaled destination.<br>
+        `(RGBA_dst` &times; `RGBA_dst_factor) - (RGBA_src` &times; `RGBA_src_factor)`
+      min: >
+        Takes the minimum of the source and destination.<br>
+        `min(RGBA_src, RGBA_dst)`
+      max: >
+        Takes the maximum of the source and destination.<br>
+        `max(RGBA_src, RGBA_dst)`
+
 bitmask:
   texture usage:
     description: Determine how a GPUTexture maybe be used after creation.