component-docs
component-docs copied to clipboard
Update Rust example with clear identifiers
Currently the Rust example often uses the same name for packages, functions, worlds, interfaces. (This might also be the case elsewhere in the book, not sure)
Example: https://github.com/bytecodealliance/component-docs/blob/31445f3501113075c4a31c6aee426b8f75933a78/component-model/src/language-support/rust.md?plain=1#L82-L92
Here the package name is the same as the world name and the interface name is the same as the function name. Once you start using it elsewhere in the example it can be very unclear if you refer to the package, world, interface,... While this works fine for someone who is just copy pasting the example, true understanding requires one to know where to reference what exactly. This example is very hard to extrapolate to other components and projects.
I would propose that the examples clearly label everything e.g., adder-package, adder-world,...
If other people agree I could create a pull-request for this.
Hey @jordithijsman we'd certainly like to have this change!
That said one thing I'd caution is adding -<type> of thing after since it would be redundant and kind of go against the point of having those keywords in the first place.
The hard part here might be coming up with different names for the world versus the functions therein, and the package name.
Also note that at this point, since the docs:adder package is published, we likely don't want to change the package name, but the world name and the interface name are fair game.