Yosh Wuyts (Jun 26 2025 at 15:32): Yosh Wuyts (Jun 26 2025 at 15:32):@Lann Martin did you have a scheme for how to embed WIT documents with comments and all in Wasm binaries? I think Luke mentioned that you'd been looking at this a while ago?
Yosh Wuyts (Jun 26 2025 at 15:34):At MS we're interested in storing all of this info in Wasm binaries so we can use that for post-processsing later on. I wanted to check if there was prior art for this already.
Lann Martin (Jun 26 2025 at 15:36):This is already done in wasm-tools
Alex Crichton (Jun 26 2025 at 15:37):(implementation here, and it's where stability is encoded too)
Yosh Wuyts (Jun 26 2025 at 15:37):ohhhh!
Yosh Wuyts (Jun 26 2025 at 15:40):cc/ @Mossaka (Joe) this should cover what we need, right? ^
Lann Martin (Jun 26 2025 at 15:40):No wonder I haven't been able to find that code! @Alex Crichton moved it!
Yosh Wuyts (Jun 26 2025 at 15:40):hahaha
Lann Martin (Jun 26 2025 at 15:41):"Where did PackageDocs go? Was it all a dream?"
Yosh Wuyts (Jun 26 2025 at 15:41):are we already populating this data from e.g. cargo-component too?
Lann Martin (Jun 26 2025 at 15:42):If you aren't parsing WIT yourself you should be populating it
Alex Crichton (Jun 26 2025 at 15:42):most likely not I think, this only affects WIT packages encoded as wasm, actual components don't use this custom section at all
Lann Martin (Jun 26 2025 at 15:42):ohh in non-WIT components, yeah not by default
Alex Crichton (Jun 26 2025 at 15:42):agreed though if you're talking about wit-encoded-as-wasm or parsing wit-encoded-as-wasm then yeah that should all be supported by default
Yosh Wuyts (Jun 26 2025 at 15:43):heh, yeah no this would be for actual components encoded as wasm - to make them self-describing in a way that other tools can post-process them
Alex Crichton (Jun 26 2025 at 15:44):ah ok, yeah for that this isn't implemented at this time (no docs/stability custom section)
Yosh Wuyts (Jun 26 2025 at 15:44):wait, to check:
Lann Martin (Jun 26 2025 at 15:44):This is the only (?) place it gets binary encoded: https://github.com/bytecodealliance/wasm-tools/blob/bc0a78578a764b3f43489e210066bc7ea2449ac5/crates/wit-component/src/encoding/wit.rs#L59-L63
Yosh Wuyts (Jun 26 2025 at 15:45):that means we can use this custom section for that, but it isn't yet integrated in e.g. cargo-component?
Alex Crichton (Jun 26 2025 at 15:46):sort of, and sort of yes. In theory this custom section could be used for docs and it almost certainly isn't integrated in cargo-component right now. That being said if it were emitted nothing would actually use such custom section as the custom section is only decoded as part of a wit-encoded-as-wasm blob
Alex Crichton (Jun 26 2025 at 15:47):making it work for a component itself would likely not actually involve cargo-component but instead wit-component which cargo-component uses, and it might not be too too hard to emit but I haven't looked much into this
Lann Martin (Jun 26 2025 at 15:47): Yosh Wuyts (Jun 26 2025 at 15:47):that all makes sense!
Lann Martin (Jun 26 2025 at 15:48):@Alex Crichton how are you feeling about the format stabilitiy? Still "fine pre-1.0 but hopefully changed eventually"?
Yosh Wuyts (Jun 26 2025 at 15:48):are there any objections if we took it that route? e.g. actually populate the package-docs custom section for components as well?
Alex Crichton (Jun 26 2025 at 15:49):that's a tough one... on one hand if it's not changed now it's probably never going to change as it'll always be easiest to just stick with it as-is, but on the other hand iunno if there's really that strong of a motivation to change it
Lann Martin (Jun 26 2025 at 15:49):For context, the doc comments at least are encoded in a somewhat ad-hoc JSON format that isn't very "wasm-y"
Yosh Wuyts (Jun 26 2025 at 15:50):Lann Martin said:
For context, the doc comments at least are encoded in a somewhat ad-hoc JSON format that isn't very "wasm-y"
ohh, I see
Alex Crichton (Jun 26 2025 at 15:50):I don't have any problem emitting this in components myself, but I'd have to double-check to see if the format is suitable for describing components as it is wit documents
Yosh Wuyts (Jun 26 2025 at 15:51):by the way, there's no time pressure on this from our end
Yosh Wuyts (Jun 26 2025 at 15:51):for our flow we can do post-processing in other ways
Yosh Wuyts (Jun 26 2025 at 15:51):but they are a little hacky
Yosh Wuyts (Jun 26 2025 at 15:51):so it would be good to eventually arrive at a canonical/standard way to include doc info for components
Mossaka (Joe) (Jun 30 2025 at 18:29):Ah great thanks for the discussion. yeah we are looking for non-wit components having WIT docstrings embedded so that the WIT extracted from the component does preserve the comments.
Lann Martin (Jun 30 2025 at 19:20):I thought about this a little last week but I don't have enough component encoding details in my head to have a clear idea of how this would work. If you already have a world matching your component then I think the custom section used for binary WIT should match the component. If you don't already have a WIT world then I believe you could construct one from the component and then merge with the original WIT to get what you need, but I haven't actually tried.
Mossaka (Joe) (Aug 17 2025 at 00:44):Got it working
image.png
Mossaka (Joe) (Aug 17 2025 at 00:47):I think it's okay in terms of UX that there is an extra post-step to inject docs into the Component, but what do you think about having a wasm-tools subcommand that can do this?
Like wasm-tools component wit --inject-docs ./wit -o output.wasm input.wasm
Lann Martin (Aug 18 2025 at 12:48):I'd probably make it a new subcommand e.g. wasm-tools component docs which is just for manipulating that custom section.
Last updated: Dec 06 2025 at 07:03 UTC