Since this is a library, you normally do this via code annotation, and once it’s published on crates.io, https://docs.rs/ will generate the documentation for you.
You can embed examples in the annotation, and
cargo test will be able to test the examples for you as well.
Add extra code comments if your crate is very critical, and you want to make sure people reviewing your code can check your design and discover errors easily.
Normally people utilise Travis-CI or other continuous integration services for this, and run kcov(code coverage measuring tool) through it, then upload the code coverage report to codecov.io or coveralls.io.
For libraries that do not require communication(no networking, no file IO, etc), you should aim to achieve above 90% code coverage. There will be some noises, so don’t freak out if you’re off by a few percent, but roughly that range.
For binaries, code coverage will be a bit tricky, you basically need to build custom scripts to run kcov on your binary with specific commands, then upload all code reports to codecov.io etc.
Files and modules organisation
There aren’t fixed standards(as expected), but generally making it very maintainable is the goal, so no overly massive files is one of the things you can do.
Make use of module separation as best as you can as well, since you can keep things private to each module, and limit usage error propagation at the moudle boundary this way.
No experience with it, sorry.
Publish a 0.X.X version first, to see if things look right on crates.io and see if docs.rs picks it up properly etc, then move onto publishing 1.0.0 version.
Following SemVer as best as you can.
Keep a changelog whether your project is a library or binary. This will help the users to determine when to update, and what new stuff can be expected.
Have some form of service to check whether the dependencies are up-to-date for you, most crates I’ve seen use deps.rs
Pointers to my stuff
You will find crates with much better practices, I’m posting my stuff purely because I’m most familiar with them and I can answer any questions readily, if you happen to have any.
- the readme has badges to the services used(docs, deps, code coverage, etc)
- Extra stuff I did
- Since this is a library for doing error correction, it is extremely important that it’s largely bug-free. Things were reviewed very thoroughly and went through a lot of code refactoring(basically every line was rewritten a few times and reviewed several times), in particular I added “audit” comments to facilitate code reviews
I probably missed a few things, but hopefully I’ve got most of them right.
Nice, looking forward to seeing the final product!