Zig 0.17.0-dev (Split by item)

This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig library itself.

render_docs

main.render_docs

fn render_docs(
    out: *ArrayList(u8),
    decl_index: Decl.Index,
    first_doc_comment: Ast.TokenIndex,
    short: bool,
) Oom!void

File

lib/docs/wasm/main.zig:682

Code

fn render_docs(
    out: *ArrayList(u8),
    decl_index: Decl.Index,
    first_doc_comment: Ast.TokenIndex,
    short: bool,
) Oom!void {
    const decl = decl_index.get();
    const ast = decl.file.get_ast();

    var parser = try markdown.Parser.init(gpa);
    defer parser.deinit();
    var it = first_doc_comment;
    while (true) : (it += 1) switch (ast.tokenTag(it)) {
        .doc_comment, .container_doc_comment => {
            const line = ast.tokenSlice(it)[3..];
            if (short and line.len == 0) break;
            try parser.feedLine(line);
        },
        else => break,
    };

    var parsed_doc = try parser.endInput();
    defer parsed_doc.deinit(gpa);

    const g = struct {
        var link_buffer: ArrayList(u8) = .empty;
    };

    const Renderer = markdown.Renderer(Decl.Index);
    const renderer: Renderer = .{
        .context = decl_index,
        .renderFn = struct {
            fn render(
                r: Renderer,
                doc: markdown.Document,
                node: markdown.Document.Node.Index,
                writer: *Writer,
            ) Writer.Error!void {
                const data = doc.nodes.items(.data)[@backingInt(node)];
                switch (doc.nodes.items(.tag)[@backingInt(node)]) {
                    .code_span => {
                        try writer.writeAll("<code>");
                        const content = doc.string(data.text.content);
                        if (resolve_decl_path(r.context, content)) |resolved_decl_index| {
                            g.link_buffer.clearRetainingCapacity();
                            resolveDeclLink(resolved_decl_index, &g.link_buffer) catch return error.WriteFailed;

                            try writer.writeAll("<a href=\"#");
                            _ = missing_feature_url_escape;
                            try writer.writeAll(g.link_buffer.items);
                            try writer.print("\">{f}</a>", .{markdown.fmtHtml(content)});
                        } else {
                            try writer.print("{f}", .{markdown.fmtHtml(content)});
                        }

                        try writer.writeAll("</code>");
                    },

                    else => try Renderer.renderDefault(r, doc, node, writer),
                }
            }
        }.render,
    };

    var allocating = Writer.Allocating.fromArrayList(gpa, out);
    defer out.* = allocating.toArrayList();
    renderer.render(parsed_doc, &allocating.writer) catch |err| switch (err) {
        error.WriteFailed => return error.OutOfMemory,
    };
}