Improve documentation and examples

[Meziu]

Closes #32

Finally, the long awaited "documentation PR" I have so much anticipated has come.

This PR's changes boil down to:

• Newly written READMEs for each package (with the idea in mind that they will eventually be read from crates.io).
• Changed Cargo.toml manifests to include all metadata required for a future release on crates.io.
• Improved examples with the addition of a better documentation that explains their behavior (except for the "threads" and "futures" examples that still need to be settled).
• A pretty substantial list of new TODOs that I discovered while thoroughly testing the crate (a lot of testing has been done...)
• #[doc(alias)] for ALL functions and structs that benefit a 1:1 relation with ctru-sys, so that users used to the C library can search for names they already know and find out how that functionality translates in ctru-rs.
• Slight bump to the minimum rust versions (the same as cargo-3ds).

And most importantly:

• COMPLETE member-by-member documentation that includes multiple documentation layers, doclinks, and small doctests/examples for most functions.

I suggest you review this PR mostly by looking at the result of the cargo 3ds doc compilation, since the git diff is huge.

This PR took me weeks of work and it marks one big milestone for this project (in some cases, the new docs are actually better than libctru's official ones :P ).

Thanks for your attention. I may finally go puke in a nearby bucket. Writing docs is nauseous 🤮 .

[FenrirWolf]

When I check out the branch and run cargo 3ds doc --open, I get the following error from shim_3ds that prevents the docs from fully building:

error[E0432]: unresolved import `ctru_sys::__errno`
 --> /home/fenrir/.cargo/git/checkouts/shim-3ds-0fd8aff15f8f05f2/2d3ebe6/src/lib.rs:3:5
  |
3 | use ctru_sys::__errno;
  |     ^^^^^^^^^^-------
  |     |         |
  |     |         help: a similar name exists in the module: `errno`
  |     no `__errno` in the root

For more information about this error, try `rustc --explain E0432`.
error: could not compile `shim-3ds` (lib) due to previous error

[Meziu]

When I check out the branch and run cargo 3ds doc --open, I get the following error from shim_3ds that prevents the docs from fully building:

error[E0432]: unresolved import `ctru_sys::__errno`
 --> /home/fenrir/.cargo/git/checkouts/shim-3ds-0fd8aff15f8f05f2/2d3ebe6/src/lib.rs:3:5
  |
3 | use ctru_sys::__errno;
  |     ^^^^^^^^^^-------
  |     |         |
  |     |         help: a similar name exists in the module: `errno`
  |     no `__errno` in the root

For more information about this error, try `rustc --explain E0432`.
error: could not compile `shim-3ds` (lib) due to previous error

You probably need to update your git cache. It’s been updated a while ago. cargo update should do the trick.

[FenrirWolf]

That's the thing though, I can build and read the docs just fine on the latest master but not on this branch. Same thing after running cargo update too.

[Meziu]

That's the thing though, I can build and read the docs just fine on the latest master but not on this branch. Same thing after running cargo update too.

I don’t really know what to tell you except cargo clean and cargo update. The function is very much there and even the CI (which uses a fresh environment) can build the documentation just fine.

[FenrirWolf]

Got them building after nuking my local project and then checking the branch out again. Not sure what that was about but at least the problem's gone now 😆

[FenrirWolf]

Other than typos and some suggestions from Github Actions that might be worth implementing, I'd say that this looks good to me