Repository navigation
Autodoc: code block is rendered incorrectly #21358
Copy link
Copy link
Closed
Labels
autodocThe web application for interactive documentation and generation of its assets.The web application for interactive documentation and generation of its assets.bugObserved behavior contradicts documented or intended behaviorObserved behavior contradicts documented or intended behavior
Milestone
Description
Zig Version
0.14.0-dev.1510+fb0028a0d
Steps to Reproduce and Observed Behavior
I have a function like this:
/// Appends the new argument to the list of arguments.
///
/// **NOTE:** It returns an `error.DuplicatePositionalArgIndex` when attempting
/// to append two positional arguments with the same index. See the examples below.
///
/// ## Examples
///
/// ```zig
/// var app = App.init(allocator, "myapp", "My app description");
/// defer app.deinit();
///
/// var root = app.rootCommand();
/// try root.addArg(Arg.booleanOption("version", 'v', "Show version number"));
///
/// var test = app.createCommand("test", "Run test");
/// try test.addArg(Arg.positional("FILE", null, null));
/// ```
///
/// Appending two positional arguments with the same index.
///
/// ```zig
/// var app = App.init(allocator, "myapp", "My app description");
/// defer app.deinit();
///
/// var root = app.rootCommand();
/// try root.addArg(Arg.positional("FIRST", null, 1));
/// // Returns `error.DuplicatePositionalArgIndex`.
/// try root.addArg(Arg.positional("SECOND", null, 1));
/// ```
pub fn addArg(self: *Command, arg: Arg) !void { ... }When I generate and look at the documentation page, I got:
Another example
/// Appends multiple arguments to the list of arguments.
///
/// ## Examples
///
/// ```zig
/// var app = App.init(allocator, "myapp", "My app description");
/// defer app.deinit();
///
/// var root = app.rootCommand();
/// try root.addArgs(&[_]Arg {
/// Arg.singleValueOption("firstname", 'f', "First name"),
/// Arg.singleValueOption("lastname", 'l', "Last name"),
/// });
///
/// var address = app.createCommand("address", "Address");
/// try address.addArgs(&[_]Arg {
/// Arg.singleValueOption("street", 's', "Street name"),
/// Arg.singleValueOption("postal", 'p', "Postal code"),
/// });
/// ```
pub fn addArgs(self: *Command, args: []const Arg) !void {
for (args) |arg| try self.addArg(arg);
}Expected Behavior
I expected correct rendering.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
autodocThe web application for interactive documentation and generation of its assets.The web application for interactive documentation and generation of its assets.bugObserved behavior contradicts documented or intended behaviorObserved behavior contradicts documented or intended behavior


Activity
rohlem commentedon Sep 9, 2024
Right now I couldn't find it, but I remember a comment from andrew that doctests should be preferred to code blocks in doc comments, since they also appear in documentation but are additionally run as tests making them easier to stay in sync with changes in the implementation.
This also generates an "Example Usage" section designed specifically for this, f.e. example in std.Build.dirnameAllowEmpty.
prajwalch commentedon Sep 9, 2024
I am ok with the
doctestsbut embedding the code block in thedocstringis common and should be supported.std.zig.tokenizer: simplify line-based tokens
std.zig.tokenizer: simplify line-based tokens