Skip to content

Conversation

AvdN
Copy link

@AvdN AvdN commented Sep 15, 2025

In case of showing error output examples, you often have to scroll horizontally to see the interesting part of the output.

E.g. the shell output of running docgen on langref.html.in looks like this (Zig Language Reference, master):

 zig build-obj invalid_doc-comment.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/invalid_doc-comment.zig:1:16: error: expected type expression, found 'a document comment'
/// doc-comment

or like this (Zig Language Reference, 0.15.1):

$ zig test test_incorrect_pointer_alignment.zig
1/1 test_incorrect_pointer_alignment.test.pointer alignment safety...thread 1098703 panic: incorrect alignment
/home/andy/dev/zig/doc/langref/test_incorrect_pointer_alignment.zig:10:68: 0x102c2a8 in foo (test_incorrect_pointer_alignment.zig)
    const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
                                                                   ^
/home/andy/dev/zig/doc/langref/test_incorrect_pointer_alignment.zig:6:31: 0x102c0d2 in test.pointer alignment safety (test_incorrect_pointer_alignment.zig)
    try std.testing.expect(foo(bytes) == 0x11111111);
                              ^
/home/andy/dev/zig/lib/compiler/test_runner.zig:218:25: 0x115cf10 in mainTerminal (test_runner.zig)
        if (test_fn.func()) |_| {
                        ^
/home/andy/dev/zig/lib/compiler/test_runner.zig:66:28: 0x1156131 in main (test_runner.zig)
        return mainTerminal();
                           ^
/home/andy/dev/zig/lib/std/start.zig:618:22: 0x114fecd in posixCallMainAndExit (std.zig)
            root.main();
                     ^
/home/andy/dev/zig/lib/std/start.zig:232:5: 0x114f761 in _start (std.zig)
    asm volatile (switch (native_arch) {
    ^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/andy/dev/zig/.zig-cache/o/0b2d2bfc37e3220ff3dbb549fa094812/test --seed=0xcf0b8a3a

In both cases the length of the path pushes the interesting information to the right, but certainly the start of that path provides no information relevant to for the person consulting the documentation.

This PR adds an option --base-dir to docgen, which, if provided with a string argument, removes that argument from output of |code| invoked Zig files. If the current directory is provided as argument (/home/ci/actions-runner/_work/zig-bootstrap/zig resp. /home/andy/dev/zig in the above examples), this shortens the lines with filenames and so reduces (and often completely eliminates) the need for horizontal scrolling when viewing an example.

build.zig has been updated to provide docgen with --base-dir <std.os.getcwd()> (there did not seem to be an allocator available to dynamically allocate the buffer for os_cwd, but maybe that is somehow available via std.Build, nor could I figure out how to provide an fs.Dir() instance as .addFileArg() argument)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant