Improvement for witgen's documentation
Closed this issue · 1 comments
Hi there!
First of all, thank you for the crate! I found it in the comments of wit-bindgen crate and it got me started with using .wit files, so thanks a lot!
After using it, I wanted to come back with some comments to improve the user experience :) Let me know if you would prefer a PR on any of these comments.
Documentation improvement
On the main example of the crate, it states "Into your Rust code:". The first thing I wondered was should I use lib.rs or main.rs?
It turns out that it "does not matter" as you can then pass the corresponding path to cargo witgen generate...
I propose to make the example fixed in lib.rs and at the end add a note that this can be also done by putting the Rust code in a binary and changing the call to cargo witgen.
Examples directory
The documentation you have put in the README and libr.rs is nice, but the curious user might also look for the examples directory. You could add the same example as a new crate (called my my-wit for example) located in the examples directory of this crate.
Limitations?
When using the cli, I wondered what features were supported and what kind of Rust code could I mark with #[witgen].
I know that the .wit specification is changing, but do you think it would be good to keep track of what is possible and what is not?
Say, in .wit there are no methods, only functions. This is correctly marked when you use #[witgen] in an impl block. The same with the use of references, as interface types are meant to be consumed by design (hope I got this right).
Since the actual Rust code that can be converted to wit is few, I would just mention it somewhere.
Body functions
While using the cli, I wondered what the functions bodies are used for. They are skipped, as they are not part of the .wit file. They are there so that the Rust compiler does not complain and serve as an "example of implementing the function".
I would add a comment somewhere that the body functions are not translated and Rust programmer could use the opportunity to write examples of functions (instead of satisfying the compiler with a todo!()).
Hi @saona-raimundo your proposals are very interesting. I would be happy to receive a PR to take care about the point Documentation improvement and also the point about Body functions. I will create the examples directory and put one of my example inside, you're right, it helps a lot ! And I will also add in the documentation what are the current limitations.