nlopes
commented
5 years ago Hi @Empty2k12, thanks for raising this.
Would you mind providing a bit more context on what you mean by code samples? Or providing me with some output from running the tests locally? That would probably help.
Reason I'm asking is that the (2 as of now) doc-tests are already running in CI, check https://github.com/nlopes/libhoney-rust/blob/master/src/lib.rs#L109 as it should work.
There's also a working client example in the examples/ folder (as long as you set the 2 necessary environment variables) which can be run issuing cargo run --example client.
I'm particularly interested in "Currently, none of the code samples work right of the box.". Assuming you're referring to the ones appearing in the READMEas they are the same ones you can find in the library docs.
There's probably something obvious I'm missing so I'd be grateful for a pointer on what's going wrong for you.
Currently, none of the code samples work right out of the box.
Rust offers two features that can be easily leveraged to ensure documentation is on-par with the current working changes:
Implement examples as doc-tests Not much explanation needed here. Doc-tests can be set to compile only, or compile and run, depending on what the code does you'd want to choose between the two.
Implement examples as integration tests This is a bit harder but will test that the library functionality stays working across branches. Integration tests can serve as excellent examples, as they touch upon most, if not all, of the functionality implemented by a library.
Both tests will need to run as a mandatory step in CI, so any braking changes can be fixed before getting merged.
I understand that this project is super-WIP, but having working documentation is crucial for on-boarding people to a library instead of driving them away