Documentation on API functions

generator/build-integration.zig

@@ -3,17 +3,30 @@ const path = std.fs.path;
 const Builder = std.build.Builder;
 const Step = std.build.Step;
 
+/// Utility functionality to help with compiling shaders from build.zig.
+/// Invokes glslc (or another shader compiler passed to `init`) for each shader
+/// added via `addShader`.
 pub const ShaderCompileStep = struct {
+    /// Structure representing a shader to be compiled.
     const Shader = struct {
+        /// The path to the shader, relative to the current build root.
         source_path: []const u8,
+
+        /// The full output path where the compiled shader binary is placed.
         full_out_path: []const u8,
     };
 
     step: Step,
     builder: *Builder,
+
+    /// The command and optional arguments used to invoke the shader compiler.
     glslc_cmd: []const []const u8,
+
+    /// List of shaders that are to be compiled.
     shaders: std.ArrayList(Shader),
 
+    /// Create a ShaderCompilerStep for `builder`. When this step is invoked by the build
+    /// system, `<glcl_cmd...> <shader_source> -o <dst_addr>` is invoked for each shader.
     pub fn init(builder: *Builder, glslc_cmd: []const []const u8) *ShaderCompileStep {
         const self = builder.allocator.create(ShaderCompileStep) catch unreachable;
         self.* = .{
@@ -25,6 +38,10 @@ pub const ShaderCompileStep = struct {
         return self;
     }
 
+    /// Add a shader to be compiled. `src` is shader source path, relative to the project root.
+    /// Returns the full path where the compiled binary will be stored upon successful compilation.
+    /// This path can then be used to include the binary into an executable, for example by passing it
+    /// to @embedFile via an additional generated file.
     pub fn add(self: *ShaderCompileStep, src: []const u8) []const u8 {
         const full_out_path = path.join(self.builder.allocator, &[_][]const u8{
             self.builder.build_root,
@@ -36,6 +53,7 @@ pub const ShaderCompileStep = struct {
         return full_out_path;
     }
 
+    /// Internal build function.
     fn make(step: *Step) !void {
         const self = @fieldParentPtr(ShaderCompileStep, "step", step);
         const cwd = std.fs.cwd();

generator/vulkan/build-integration.zig

@@ -4,13 +4,24 @@ const path = std.fs.path;
 const Builder = std.build.Builder;
 const Step = std.build.Step;
 
+/// build.zig integration for Vulkan binding generation. This step can be used to generate
+/// Vulkan bindings at compiletime from vk.xml, by providing the path to vk.xml and the output
+/// path relative to zig-cache. The final file can then be added to the project using
+/// `std.build.Builder.addPackagePath`.
 pub const GenerateStep = struct {
     step: Step,
     builder: *Builder,
+
+    /// The path to vk.xml
     spec_path: []const u8,
+
+    /// The full path where the final generated binding will be placed. When using this step,
+    /// this path should be passed to addPackagePath.
     full_out_path: []const u8,
 
-    // out_path is relative to builder.cache_root
+    /// Initialize a Vulkan generation step, for `builder`. `spec_path` is the path to
+    /// vk.xml, relative to the project root. The generated bindings will be placed at
+    /// `out_path`, which is relative to the zig-cache directory.
     pub fn init(builder: *Builder, spec_path: []const u8, out_path: []const u8) *GenerateStep {
         const self = builder.allocator.create(GenerateStep) catch unreachable;
         self.* = .{
@@ -26,6 +37,10 @@ pub const GenerateStep = struct {
         return self;
     }
 
+    /// Internal build function. This reads `vk.xml`, and passes it to `generate`, which then generates
+    /// the final bindings. The resulting generated bindings are not formatted, which is why an ArrayList
+    /// writer is passed instead of a file writer. This is then formatted into standard formatting
+    /// by parsing it and rendering with `std.zig.parse` and `std.zig.render` respectively.
     fn make(step: *Step) !void {
         const self = @fieldParentPtr(GenerateStep, "step", step);
         const cwd = std.fs.cwd();

generator/vulkan/generator.zig

@@ -326,6 +326,10 @@ pub const Generator = struct {
     }
 };
 
+/// Main function for generating the Vulkan bindings. vk.xml is to be provided via `spec_xml`,
+/// and the resulting binding is written to `writer`. `allocator` will be used to allocate temporary
+/// internal datastructures - mostly via an ArenaAllocator, but sometimes a hashmap uses this allocator
+/// directly.
 pub fn generate(allocator: *Allocator, spec_xml: []const u8, writer: var) !void {
     const spec = try xml.parse(allocator, spec_xml);
     defer spec.deinit();