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!()).

Thanks for the crate!

I wanted to ask if there could be documentation support.

Wit supports only comments and does not differentiate between documentation and code comments. But, when using wit-bindgen to transform to markdown, comments are part of the generated .md and correctly located.

Proposal

I propose to make use of this to pass over documentation comments in Rust as comments (using \\) to the generated .wit file.
Code comments in the Rust file would be ignored.

Use case

At the end of the day, the objective is to generate the .wit file that people possibly outside of the Rust world can use, therefore it makes sense to me to generate the documentation also outside of the Rust world.

I do not have experience in this type of macros, but I could do the research if needed.

As pointed out in #35, we are out of date with the wit standard.

run cargo install cargo-witgen In MacOS:

➜  my_wit git:(main) ✗ cargo witgen
error: no such subcommand: `witgen`

I rename ~/.cargo/bin/cargo_witgen to ~/.cargo/bin/cargo-witgen, and then ok.

Currently this comment is at the top of the final generated wit file. This line could also indicate which version of witgen was used to produce the file.

// This is a generated file by witgen (https://github.com/bnjjj/witgen), please do not edit yourself, you can generate a new one thanks to cargo witgen generate command

• rename (to rename a struct, enum, type or function)

cargo add --help

returns

error: no such subcommand: `add`

        Did you mean `d`?

Version:

cargo 1.58.0 (7f08ace4f 2021-11-24)

Is this a subcommand you have to install?

In the last update cargo_witgen, didn't update the dependency to the newest version.

I think perhaps it's finally time to invest in a GH action to handle the versioning and publishing.

First off, fantastic work! Worked out of the box and am excited to help with the project.

One issue I ran into is trying to generate wit from a dependencies. Within the project worked wonders, but I'm guessing the the cli is only checking the source files of the current project.

Without this, I'm wondering if there is a way to publish the wit with cargo?

Again great work and look forward to getting this in the hands of devs working with NEAR smart contracts!

This issue outlines the current work in wit-bindgen: bytecodealliance/wit-bindgen#201

They also recently created a 0.1.0 tag for the project. I took this as an opportunity to publish aha-wit-parser, which has the same version just different name. It can be added like so:

wit-parser = { version = "0.1.0", package = "aha-wit-parser" }

• Add parser as a test dep
• Update key words and syntax changes
• Generate a wit AST instead of string

Currently the runtime of the tooling can be slow because it requires compiling the project. So while once the project is stable it's quick, any edit can add some time to the rerun.

The current approach has the limitation that dependencies aren't caught by the macro. Instead the cargo crate could be used to generate a list of all source files used in the project.

This would allow using syn to analyze each file for a witgen macro. Or alternatively witgen could be inserted to any type that is part of the root crate's public API.

Hi, I think I caught a bug in witgen. When I run cargo witgen generate on this code:

use witgen::witgen;

#[witgen]
fn works() {}

#[witgen]
fn doesnt_work(handle: i32) -> i32 { handle }

#[witgen]
struct Works { test: i32 }

#[witgen]
struct DoesntWork { handle: i32 }

Then it creates this WIT file:

// auto-generated file by witgen (https://github.com/bnjjj/witgen), please do not edit yourself, you can generate a new one thanks to cargo witgen generate command. (cargo-witgen v0.15.0) 

works: func()


record works {
  test: s32
}

The function doesnt_work and the struct DoesntWork are missing.

There is no error being reported from the cargo witgen generate command.

I am using cargo-witgen v0.15.0, the witgen crate is also v0.15.0.

Because license in Cargo.toml is currently specified as license-file = ..., it shows up as "non-standard" on crates.io and makes automated license checks harder, too.

When a license is standard, it's better to use the standard SPDX identifier via license = ... field instead.

The generated wit files result in an error when trying to use them with (some!?) other tools. Especially those coming from the bytecode alliance (wasmtime, wit-bindgen, etc.). I guess current generated wit files would work with wai-bindgen and others.

I'm not quite sure why. My guess is that declaring one of default, world or interface as a top-level declaration was not mandatory before.

Do you want to change the implementation so that one of these top level declarations will be present in the generated output?

If so how would the implementation actually look? Would all Rust declarations that are annotated with only the witgen macro automatically be added to the "default" interface + the ability to pass in a world and / or interface the declaration should belong to?