Making the public API more familiar

[brycx]

The public API for streaming structs and newtypes could be made more familiar to users that come from other Rust crypto libraries.

In continuation of trying to make the streaming API more consistent (#87) the general approach seems to be that all one-shot functions are also part of the struct (an example of this is the RustCrypto Digest trait). Maybe the current should be changed to:

• module::one_shot_function() -> module::Ctx::one_shot_function()
• module::verify() -> module::Ctx::verify()

For the newtypes API, to be more consitent with types throughout Rust, we chould change:

• get_length -> len

Changing the newtype API seems worthwhile, but it's debatable whether changing the straming struct API will make a noticable difference in usability.

[colelawrence]

Is moving the functions from module to impl potentially more ergonomic, because you can now call ctx.verify etc? And it will be based on the type of ctx itself?

[brycx]

It will be based on the implementation of Ctx itself. Currently the module has the same name as Ctx, but this might change in the future if more variants of Ctx are added to the module, for example both SHA256 and SHA512 exist in a sha2 module, thus making a module-level verify() function confusing and will result in duplicate version of it at module-level.

ctx.verify will not exactly be available though, because verifying using incremental processing isn't provided, so it'll remain that you need to provide all the data at call: Ctx::verify().

[colelawrence]

Just for more information: we could technically add the new function and use a deprecated warning on the previous usage, right?

[brycx]

We could do that, but I don't think it makes much sense in this case. There is already a list of breaking changes coming up for the next major version bump. Marking these functions deprecated in the next major version would simply require another major version bump before they could be completely removed.

Aside from that, I personally don't feel marking functions as deprecated really does any good. For example, orion will fail to compile if any warnings are issued by the compiler, which will happen if one of its dependencies deprecates something (this happened with getrandom recently) and thereby break orion. So it'll depend on users whether deprecation is breaking or not.

[colelawrence]

Gotcha! The approach sounds good to me.

[brycx]

Fixed in #107.