Provide example code in source form

[Jacalz]

There is an examples/ folder but it seems to only contain examples in compiler binaries (if I understand it correctly). It would be great if some short and readable examples could be added. My idea is to have something similar to https://github.com/psanford/wormhole-william/tree/master/examples.

[piegamesde]

The examples folder only contains some files for the tests :D

This is definitely a historical artifact and should be corrected. I think the best way to get people started would be to add some snippets inline in the Rustdoc. Some larger examples in the folder would be cool too though.

[mberry]

Used the library not long ago for an android app. Would be happy to add the send and receive code as examples.

I'll give the inline docs a go too but not that familiar with wormhole protocol terminology so it might need a bit of a cleanup.

[piegamesde]

@mberry Really cool, that would be appreciated. Also you made a wormhole-rs android app? I'm intrigued ^^

Rustdocs are pretty easy actually. You just write normal markdown text. Use normal triple backticks for code blocks. Set the language of the code block to "rust" and you'll automatically get a doctest. Set it to "no_run" and it will at least compile them. Within the code block, you can prefix lines with # to hide them from the output to make examples more concise (i.e. to hide some mockup type definitions). Test your changes with cargo doc --open and cargo test --doc then iterate.

[mberry]

Started on a full working example binary and came around to your original conclusion that inline docs are probably more helpful. There's a fair bit involved in mocking a peer to send a file locally, not even sure if you can send to the same IP address easily.

Did a few doc examples yesterday in core and transfer and will try to get some more done today. Should I submit the PR to the dev branch?

Was hoping to avoid no_run on the functions that can be built into tests but ran into an issue on send_file(). Even when putting a future::Ready into cancel it still waits as though it's been given a Pending, from what I gathered a completed future should cancel the function and move on? Briefly went through some of the code but couldn't really grok why it was happening. So for now I guess there's a few that will get the no_run marker even though they shouldn't really need it.

Also due to the library not being a default member in the workspace you actually need to specify it to test and build docs: cargo test --doc --package magic_wormhole and cargo doc --package magic_wormhole --no-deps

Cheers!

[piegamesde]

There's a fair bit involved in mocking a peer to send a file locally, not even sure if you can send to the same IP address easily.

This shouldn't be required. Just put the code for one side in the documentation. It does not need to run, it just needs to compile. If you really want to have both sides, you can have a look at how the rust2rust test is handling this.

Also due to the library not being a default member in the workspace you actually need to specify it to test and build docs

Would cargo test --doc --all work instead?

[piegamesde]

Should I submit the PR to the dev branch?

Against master please if the changes are mostly self-contained.