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

[FenrirWolf]

Looks like the things I saw from Github Actions weren't actually caused by this PR so they don't need to block it. I think this looks good to merge

[adryzz]

great job! LGTM

[ian-h-chamberlain]

Wow, awesome work!!! This is really a huge step forward for the library and looks like it took a lot of effort, so thank you!

Many of my comments are just little typos or minor wording change suggestions, so feel free to ignore them as you want. I probably missed some stuff but I tried to look at everything I could, so hopefully some of it is helpful.

This is really exciting!