Autoformat documentation examples and update README

[MarijnS95]

As mentioned in 1 the documentation example could use some autoformatting, and recent API changes have to be propagated into the README too.

---

I'm curious if we should just paste the full working example in README, that's much clearer IMO, or refernce. @katyo given your CI efforts you might like https://docs.rs/doc-comment/, a crate that (build)tests the documentation in arbitrary markdown files like README.md from build.rs. If we put a fully working example here we can also make sure that it stays in a compiling state :)

[Drakulix]

Thanks!

[katyo]

@MarijnS95, I'm on a way to adopt another approach in my crates. I simply used cargo-readme to generate READMEs from doc comment. In addition I added CI rules which helps update README when docs changed.
See the katyo/aubio-rs#18 for example.

@Drakulix, I don't sure how such approach applicable here but looks like much simpler.

[MarijnS95]

@katyo That seems like a pretty cool idea! Most READMEs are partial duplicates of the documentation header and apparently it even supports templates to generate the readme. And it strips # comments from rustdoc codeblocks too!

I'll have to try this out some time, maybe this GBM crate with a relatively slim readme is a good place to start :)

[MarijnS95]

Check with our documentation, unfortunately it doesn't strip empty comment lines with //! # - but when replaced //! (unsurprisingly so) empty lines show up :/

EDIT: That'll be fixed by webern/cargo-readme#67.

[Drakulix]

@Drakulix, I don't sure how such approach applicable here but looks like much simpler.

I really like that idea. 👍
Would be cool if someone could follow up with a PR.

[MarijnS95]

@Drakulix, I don't sure how such approach applicable here but looks like much simpler.

I really like that idea. 👍
Would be cool if someone could follow up with a PR.

@Drakulix you have one in #11, but it's blocking on a fix on their side. Review and suggestions welcome :)