component-docs
component-docs copied to clipboard
bytecodealliance
feat: improve JS lang docs
Hi @kate-goldenring sorry for the delay in responding here -- While working on jco I was looking at the docs and realized that the javascript section wasn't quite as filled out as the Rust section. I originally started trying to at least add similar sections the JS version, but the effort kind of grew :sweat_smile:
Ideally I'd like to at least have some more code sections/examples for the JS stuff that matches Rust/some of the other developed toolchains -- apologies, I should have made an issue first to capture what I wanted to add.
Hey @kate-goldenring also another thing here -- in an bid to lower the scope of this PR, what do you think about moving the code examples to jco directly and linking to them from here? Just thinking back on this, the PR isn't done yet but it's probably unreasonable to include the code here when it could be kept a bit closer to jco (and possibly kept under test)
@vados-cosmonic, I think the scope of this PR is reasonable. To me, it adds a second example host, namely a JCO one in addition to our current rust one. Once this is in a state you deem ready to review and after merging, we can move both host CLI examples into one folder. I would love to get these updates to javascript.md in.
@vados-cosmonic just want to check in here. Do you want to change the scope of this PR or prioritize getting in a certain section of it?
Hey @kate-goldenring sorry for the delay here -- I'm going to try and get this done this week! I'm fine keeping the scope the same, and if the code gets overbearing we can always move it out to jco (we could use an examples folder at the top level in there anyway)
Hey @kate-goldenring sorry for the delay here, but the branch is finally looking reasonable!
There's a lot of new code (all those new lines are mostly from package-lock.jsons!), but this should now be a quite complete introduction to the early parts of
Full disclosure, I had some sections that I removed -- particularly the way types are translated, how to run with wasi:cli and how to use resources -- the PR is already long enough as is! If possible I'd like to contribute those sections in a follow up.
Oh also ping @guybedford -- any comments you have would be greatly appreciated :)
I'm also of half a mind to link to these examples (or copy them outright?) to jco as well, that repo would benefit from an examples folder I think!
Hey @kate-goldenring thank you for taking the time and the detailed review!
Just to hit the points in your overview (which was also helpful!) -- I agree on the structure, and thanks for letting me know the intended organization, that sounds fine to me.
Changing to a new structure should probably follow a more proper issue + discussion + PR process. I was hoping this change was small, and clearly... it's no longer that! :sweat_smile:
The examples/tutorial folder is for all components and host runtimes that have to do with implementing or executing the calculator world. The cli-calc.js executes evalExpression from that world. Can you add it back in?
Absolutely, will add this back in!
You provide a new host for the example world. Can you move it (run-transpiled.js) to examples/example-host and update your example to use that WIT as well (the example world) rather than renaming it to adder world.
Will do this as well! The host in example-host is Rust-based, but the host in run-transpiled is JS based, does it make sense to split those up? examples/hosts/js & examples/hosts/rust ?
For now, can you remove your example implementation of the add component? We don't provide any example implementations for other languages. In the future, we may want to create a example/example-world folder with example hosts and impls below that.
I'd recommend adding the string-reverse and string-reverse-upper examples to JCO where they can be better maintained. If that isn't an option, in the least, they should be moved to the top level of the examples directory.
Yup, will remove the add component -- I'll move that to jco probably along with most of the other examples, it's probably bit much to have the code essentially reproduced in the docs and committed to the documentation project. These examples make a lot of sense as part of jco.
Again, thanks for the reviews and general feedback as well -- will get to making these changes soon!
Hey @kate-goldenring thanks for taking another look at this -- with the exception of one of the things you pointed out, I've been able to address the other issues! The alerts render just fine as well though WARN should have been WARNING!
Hey @kate-goldenring if you wouldn't mind taking another look -- I've mirrored the other guides and kept in the more advanced sections, with links back to jco for the full code listing.
Hey @kate-goldenring thanks for the tireless reviews -- apologize for taking up so much of your time! With the edits, the documentation is so much better.
Would love your help maintaining this document and other documentation as time allows. I would love to help wherever I can, this time with the proper flow! If there are issues that are reasonable for someone in the Rust & JS ecosystems to tackle I'm certainly happy to help.
For the reactor component thread, lets continue that discussion and we can always update the doc. Yes, this time I'll make some issues to start!