Generating documentation for *opaque only shows source code

Help
1

Is there a good reason why getEmittedDocs doesn’t generate documentation for *opaque?

What I mean is, lets say we have the following code:

/// Documentation for anOpaque
pub const anOpaue = opaque {
    
    /// Documentation for fnTakesOpaque
    pub fn fnTakesOpaque(input: anOpaue) void {

        std.debug.print("got and opaque: {any}", .{input});

    }
};

/// Documentation for PointerOpaque
pub const PointerOpaque = *opaque {

    /// Documentation for fnTakesPointerOpaque
    pub fn fnTakesPointerOpaque(input: PointerOpaque) void {

        std.debug.print("got and opaque: {any}", .{input});
    }
};

The generated documentation would look somewhat like this for Opaque

opaque

Documentation for anOpaque

Functions

pub fn fnTakesOpaque(input: anOpaue) void

  Documentation for fnTakesOpaque

But for *opaque one gets

Type

Documentation for PointerOpaque

Source Code

pub const PointerOpaque = *opaque {

    /// Documentation for fnTakesPointerOpaque
    pub fn fnTakesPointerOpaque(input: PointerOpaque) void {

        std.debug.print("got and opaque: {any}", .{input});
    }
}
2

Have you tried to do it in two steps?
not sure if that helps…

pub const PointerOpaque = *OpaqueDef;
pub const OpaqueDef = opaque {

    /// Documentation for fnTakesPointerOpaque
    pub fn fnTakesPointerOpaque(input: PointerOpaque) void {

        std.debug.print("got and opaque: {any}", .{input});
    }
};
3

What seems to be the real issue to me here is that you are even able to make a *opaque block. Have you tried actually using this PointerQueue? I’ve done a quick test in the playground:

const std = @import("std");

const Foo = *opaque {
    pub fn wtf(_: @This()) void {
        std.debug.print("{s}", .{@typeName(@This())});
    }
};

pub fn main() void {
    const foo: Foo = @ptrFromInt(42);
    foo.wtf();
}

and it seems basically unusable:

main.zig:4:16: error: parameter of opaque type ‘main.Foo__opaque_3387’ not allowed
main.zig:3:14: note: opaque declared here (exit status 1)

This makes sense to me insofar as *opaque {} shouldn’t even be a thing, in the same way that *struct {} or *enum {} aren’t. That the compiler doesn’t signal the problem at the level of PointerQueue definition seems like a bug, since, like I said, the methods you put into this weird namespace cannot really be used.

In your particular case, fnTakesPointerOpaque could be put into anOpaque directly if both opaques refer to the same conceptual FFI type. Otherwise you should just define the second block as regular opaque{} and have the method take a *@This() parameter (i.e., a pointer).

4

A bare @This() refers to the (dereferenced) value of the opaque type, which is not representable because its size is unknown. If you change it to *const @This() your code compiles and runs.

1 Like
6

yeah this is probably the way forward for me if its intended to not be able to generate automatic doc for *opaque.

7

Defining *opaque{} with fns inside works fine. Have it in a lot of places.

8

@This doesn’t work but the following does,

const std = @import("std");

const Foo = *opaque {
    pub fn wtf(input: Foo) void {
        std.debug.print("{any}", .{input});
    }
};

pub fn main() void {
    const foo: Foo = @ptrFromInt(42);
    foo.wtf();
}

main.Foo__opaque_2553@2a

1 Like