Refactor README code examples

antoyo / relm

Idiomatic, GTK+-based, GUI library, inspired by Elm, written in Rust

MIT License

2.44k stars 78 forks source link

Refactor README code examples #81

Open zzeroo opened 6 years ago

zzeroo commented 6 years ago

The examples in the projects README does not work if you create a project from them.

I've create working examples:

for the first part https://gist.github.com/zzeroo/c63499d1a320b4eff5325728600e7524
and the second #[widget] example https://gist.github.com/zzeroo/07155d47bf97876dcdc4c11bed731ba9

Currently they contain unnecessary code e.g. https://gist.github.com/zzeroo/c63499d1a320b4eff5325728600e7524#file-readme1-rs-L68-L74 and they match not very well. I mean the first part is not straight an ancestor of the second.

What do you think, can I contribute a better version of the README?

antoyo commented 6 years ago

What's not working with the README examples? Please not that the second is based on the first, which may be why it doesn't compile. Thanks.

zzeroo commented 6 years ago

That's the jumping point. I recognized that. But it's also why I ask first. Maybe I don't overlook the whole.

But please compare my first example with the actual README. The order of the rows should match more or less. There are some missing elements. And some non commented parts which make the code not clear compiling.

The second part was also hard for me as very noobish rookie. It was not clear which parts you have to remove, the relm errors were not helpful either.

zzeroo commented 6 years ago

but to be honest. You're right. It's just little details:

some missing imports https://gist.github.com/zzeroo/c63499d1a320b4eff5325728600e7524#file-readme1-rs-L13-L15
missing comment: https://gist.github.com/zzeroo/c63499d1a320b4eff5325728600e7524#file-readme1-rs-L60-L63 for the first part. But the second has some more missings

antoyo commented 6 years ago

Ok, that would be helpful indeed. Thanks for doing that. If you need any help, don't hesitate to ask.

antoyo commented 6 years ago

We should also have a way to automatically test the examples in the readme.

Eijebong commented 6 years ago

I remember seeing a crate doing that. I can't remember the name of it though...

antoyo commented 6 years ago

Note to myself: just include test files inside the readme and they will always be up to date.

Eijebong commented 6 years ago

@antoyo You could also write something like https://github.com/lettre/lettre/pull/253

chathaway-codes commented 5 years ago

Maybe related to this issue, but the README is currently suggesting version gtk 0.3.0 and relm 0.11.0. That is a few versions behind, according to crates.io (gtk 0.60, and relm 0.16.0 are the versions as the moment of this comment). They should probably be updated, especially for those people who first started with the README, then tried to expand on an example and got a bunch of weird compilation errors.

chathaway-codes commented 5 years ago

created https://github.com/antoyo/relm/pull/169 for that small issue