search

magic-wormhole / magic-wormhole.rs

Rust implementation of Magic Wormhole, with new features and enhancements
European Union Public License 1.2
648 stars 72 forks source link

Provide example code in source form #154

Open Jacalz opened 2 years ago

Jacalz commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Should I submit the PR to the dev branch?

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