Refactor modification of scopes

[philippeitis]

• add_scope is simplified to simply add scopes, and no longer takes an Option<_> item.
• Added add_scopes convenience function, which allows adding multiple scopes at once.
• Added clear_scopes function to explicitly allow clearing method scopes.

This also includes small improvements to documentation - primarily by including links to referenced types / methods

Addresses #333

[Byron]

Thanks a lot for this contribution, so much better!

Drive3 v5.0.1 was released as canary if you will, and the version prior to it was yanked. We can keep doing that with other breaking changes and when it seems to stabilize we can re-release all crates.

Speaking of, something I didn't remember doing this year was to update all API specifications, while possibly pulling in entirely new APIs. This would definitely be good to do before releasing all crates and it's something you could do if it interests you. Let's get there when we get there :).

[philippeitis]

Sure, that sounds good. However, yanking crates seems like a bad way of going about beta testing. I think you can attach a suffix like "-beta.(beta-version)" to show that a particular crate version isn't ready for release:

Example from clap: https://docs.rs/clap/4.0.0-rc.2/clap/index.html
This would cause less disruption and clearly signal to end-users that the current crate may undergo breaking changes.

[Byron]

However, yanking crates seems like a bad way of going about beta testing. I think you can attach a suffix like "-beta.(beta-version)" to show that a particular crate version isn't ready for release:

I agree, especially as having a direct dependency to a yanked crate would probably force a user to upgrade (at least it's explicit) to a breaking change. Beta-versions are tricky in cargo unfortunately as it will happily upgrade between beta versions, beta-2 is just a patch to beta-1 for example, but I don't know what it does with 5.0.1-beta and 5.0.2-beta. My guess is it will just upgrade these automatically on the next cargo update as well.

That said, and despite probably being unable to completely prevent breakage while cargo works that way, adding a beta-X suffix (or maybe even alpha) is explicit and should be preferred.