Stream: wit-bindgen

Topic: wit-parser crate: docs for function params and results

Randy Reddig (Jan 26 2024 at 20:11):

I’m working on the Go bindings for wit-bindgen (wit-bindgen-go), which consumes the JSON output of wasm-tools comonent wit -j ....

I noticed that it’s convention to document function parameters (and sometimes results), but those docs aren’t represented in the params data structure in the wit-parser crate.

Was this intentional? Would folks be interested in a PR that adds docs to function params in the wit-parser crate?

Randy Reddig (Jan 26 2024 at 20:12):

For example, wasi:io/streams.input-stream#read: https://github.com/WebAssembly/wasi-io/blob/324be895965666805cb1c622ed4f071b9e3cbd65/wit/streams.wit#L59C1-L63C1

Randy Reddig (Jan 26 2024 at 20:12):

        read: func(
            /// The maximum number of bytes to read
            len: u64
        ) -> result<list<u8>, stream-error>;

Randy Reddig (Jan 26 2024 at 20:12):

I’d like to be able to faithfully represent the docs on the len param in the generated Go code.

Lann Martin (Jan 26 2024 at 21:20):

Seems reasonable to me, though we've also discussed putting argument docs in some structured docstring annotation

Randy Reddig (Jan 26 2024 at 21:29):

Here’s an example I generated by hand from the WIT: https://github.com/ydnar/wasm-tools-go/blob/ca95a32c1bd7a53e64cddf6ca262f85ccfece45c/wasi/filesystem/types/types.wit.go#L583-L592

Randy Reddig (Jan 26 2024 at 21:29):

The WIT docs conventions map reasonably well to Go doc conventions, including Markdown footer links

Till Schneidereit (Jan 27 2024 at 13:01):

I like the idea of using these kinds of inline docs for arguments. As Lann said, we've discussed using structured doc comments for argument documentation, so we'd have to figure out if/how to make the combination work. I.e., do we want to make them mutually exclusive? If not, does one shadow the other? Or do they get concatenated?

None of this seems prohibitive at all, of course!

Last updated: Dec 23 2024 at 12:05 UTC