Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Autodoc: empty lines are being rendered after the each docstring line in the source code page #21360

Closed
prajwalch opened this issue Sep 9, 2024 · 6 comments · Fixed by #21371
Labels
autodoc The web application for interactive documentation and generation of its assets. bug Observed behavior contradicts documented or intended behavior
Milestone

Comments

@prajwalch
Copy link

Zig Version

0.14.0-dev.1510+fb0028a0d

Steps to Reproduce and Observed Behavior

Given a function:

/// Appends the new subcommand to the list of subcommands.
///
/// ## Examples
///
/// ```zig
/// var app = App.init(allocator, "myapp", "My app description");
/// defer app.deinit();
///
/// var root = app.rootCommand();
///
/// var test = app.createCommand("test", "Run test");
/// try test.addArg(Arg.positional("FILE", null, null));
///
/// try root.addSubcommand(test);
/// ```
pub fn addSubcommand(self: *Command, new_subcommand: Command) !void { ... }

This is what the source code of it looks like in the source page:
image

Expected Behavior

I expected correct rendering :)

@prajwalch prajwalch added the bug Observed behavior contradicts documented or intended behavior label Sep 9, 2024
@Vexu
Copy link
Member

Vexu commented Sep 9, 2024

Can't reproduce on 0.14.0-dev.1513+de8cece6e with zig build-exe a.zig -femit-docs:

/// Appends the new subcommand to the list of subcommands.
///
/// ## Examples
///
/// ```zig
/// var app = App.init(allocator, "myapp", "My app description");
/// defer app.deinit();
///
/// var root = app.rootCommand();
///
/// var test = app.createCommand("test", "Run test");
/// try test.addArg(Arg.positional("FILE", null, null));
///
/// try root.addSubcommand(test);
/// ```
pub fn main() void {
}

image

@prajwalch
Copy link
Author

prajwalch commented Sep 9, 2024

Uh, let me try one more time. By the way, which OS are you on?

Update: Got the same result. I am generating docs with zig test src/lib.zig and this is what lib.zig contains.

image

Update: I am on Windows.

@Vexu
Copy link
Member

Vexu commented Sep 9, 2024

Does it reproduce on the snippet I gave? And I'm on Linux.

@prajwalch
Copy link
Author

prajwalch commented Sep 9, 2024

Does it reproduce on the snippet I gave? And I'm on Linux.

It doesn't.

Update: Also, the issue #21358 is not reproduced on the snippet you gave it to me.

@pfgithub
Copy link
Contributor

pfgithub commented Sep 9, 2024

Both issues reproduce for me if carriage returns are inserted before every newline

image

image

@prajwalch
Copy link
Author

prajwalch commented Sep 10, 2024

Yes! Changing the CRLF to LF solves the problem.

ianprime0509 added a commit to ianprime0509/zig that referenced this issue Sep 10, 2024
Closes ziglang#21358
Closes ziglang#21360

This commit modifies the `multiline_string_literal_line`, `doc_comment`,
and `container_doc_comment` tokens to no longer include the line ending
as part of the token. This makes it easier to handle line endings (which
may be LF, CRLF, or in edge cases possibly nonexistent) consistently.

In the two issues linked above, Autodoc was already assuming this for
doc comments, and yielding incorrect results when handling files with
CRLF line endings (both in Markdown parsing and source rendering).

Applying the same simplification for multiline string literals also
brings `zig fmt` into conformance with
ziglang/zig-spec#38 regarding formatting of
multiline strings with CRLF line endings: the spec says that `zig fmt`
should remove the CR from such line endings, but this was not previously
the case.
@Vexu Vexu added the autodoc The web application for interactive documentation and generation of its assets. label Sep 10, 2024
@Vexu Vexu added this to the 0.14.0 milestone Sep 10, 2024
@Vexu Vexu closed this as completed in 9007534 Sep 10, 2024
DivergentClouds pushed a commit to DivergentClouds/zig that referenced this issue Sep 24, 2024
Closes ziglang#21358
Closes ziglang#21360

This commit modifies the `multiline_string_literal_line`, `doc_comment`,
and `container_doc_comment` tokens to no longer include the line ending
as part of the token. This makes it easier to handle line endings (which
may be LF, CRLF, or in edge cases possibly nonexistent) consistently.

In the two issues linked above, Autodoc was already assuming this for
doc comments, and yielding incorrect results when handling files with
CRLF line endings (both in Markdown parsing and source rendering).

Applying the same simplification for multiline string literals also
brings `zig fmt` into conformance with
ziglang/zig-spec#38 regarding formatting of
multiline strings with CRLF line endings: the spec says that `zig fmt`
should remove the CR from such line endings, but this was not previously
the case.
richerfu pushed a commit to richerfu/zig that referenced this issue Oct 28, 2024
Closes ziglang#21358
Closes ziglang#21360

This commit modifies the `multiline_string_literal_line`, `doc_comment`,
and `container_doc_comment` tokens to no longer include the line ending
as part of the token. This makes it easier to handle line endings (which
may be LF, CRLF, or in edge cases possibly nonexistent) consistently.

In the two issues linked above, Autodoc was already assuming this for
doc comments, and yielding incorrect results when handling files with
CRLF line endings (both in Markdown parsing and source rendering).

Applying the same simplification for multiline string literals also
brings `zig fmt` into conformance with
ziglang/zig-spec#38 regarding formatting of
multiline strings with CRLF line endings: the spec says that `zig fmt`
should remove the CR from such line endings, but this was not previously
the case.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
autodoc The web application for interactive documentation and generation of its assets. bug Observed behavior contradicts documented or intended behavior
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants