bytecodealliance
Document how imports work
As noted in https://github.com/bytecodealliance/ComponentizeJS/issues/88, it is not obvious how imports work. While I understand the hesitation to document this extensively as things are likely to change in the future, it makes it very hard for new comers to ComponentizeJS to use the tool if there is absolutely no documentation about how to call imports.
Yes, ideally this is also resolved by generating types or boilerplates via https://github.com/bytecodealliance/ComponentizeJS/issues/48, as that would allow editor integration without needing to check reference documentation.
For reference documentation, the first step here is to fully document the WIT type structure used in the Jco project, for which I've posted https://github.com/bytecodealliance/jco/issues/418.
With the WIT types fully defined there, the definition of imports here is then simply "import the corresponding WIT type by its fully qualified import name".
the definition of imports here is then simply "import the corresponding WIT type by its fully qualified import name".
I think this deserves to be documented now even before the other pieces are in place (albeit perhaps not so tersely as this particular description). From experience, once I know how to import a module that is generated from corresponding wit types, it's a lot easier to intuit how wit types are being translated into JavaScript syntax. The missing piece that took me the longest to figure out was what actually needs to go in the module string in an import statement. While the choice is obvious in hindsight, having it documented would have been very helpful even if a thorough explanation of how wit is translated into JavaScript was not included.
At the very least, including an import in the example would go a long way. At least then, it becomes possible to cargo cult.
I've added a simple example here in https://github.com/bytecodealliance/ComponentizeJS/commit/519256f5632f48e42cfea54bfd588f383eccb855.