Skip to content

Autodoc: code block is rendered incorrectly #21358

Closed

Description

@prajwalch

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:

Screenshot 2024-09-09 at 12-30-24 test Command - Zig Documentation

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);
}

Screenshot 2024-09-09 at 12-36-20 test Command - Zig Documentation

Expected Behavior

I expected correct rendering.

Activity

  1. added
    bugObserved behavior contradicts documented or intended behavior
    on Sep 9, 2024
  2. added
    autodocThe web application for interactive documentation and generation of its assets.
    on Sep 9, 2024
  3. added this to the 0.15.0 milestone on Sep 9, 2024
  4. rohlem commented on Sep 9, 2024

    @rohlem
    Contributor

    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.

  5. prajwalch commented on Sep 9, 2024

    @prajwalch
    Author

    I am ok with the doctests but embedding the code block in the docstring is common and should be supported.

  6. added a commit that references this issue on Sep 10, 2024
    b482af8
  7. modified the milestones: 0.15.0, 0.14.0 on Sep 10, 2024
  8. added a commit that references this issue on Sep 24, 2024
    b473123
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    autodocThe web application for interactive documentation and generation of its assets.bugObserved behavior contradicts documented or intended behavior

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions