This task is an outcome of #845

While documenting the framing_sv2 crate, a lot of things stood out as needing to refactor.

The documentation effort was an immediate action, while a refactoring (which implies breaking API changes) is not so urgent priority, so for now we should leave this in the backlog for an appropriate moment in the future.

Below are the different items that I believe deserve to be rewritten on framing_sv2 crate.

rename framing2.rs

the character 2 in filename framing2.rs seems to make some kind of allusion to SV2, but this isn't following any pattern or convention in naming files.

so IMO this file should be renamed to framing.rs.

Frame trait removal

The Frame trait is unnecessary. It is never really used anywhere in the code as a Trait bound. The only usage of this trait is in the impl Frame blocks for Sv2Frame and HandShakeFrame. I even did a quick experiment where I commented out the Frame trait declaration and with small adaptations, I easily got the code to compile and run without errors.

The Frame trait makes some impositions into the APIs of Sv2Frame and HandShakeFrame structs by trying to unify them logically (they're both kinds of "frame"). But unfortunately, the resulting APIs are unintuitive, more complex, and dirtier than they need to be.

For example, the Sv2Frame::payload method is emitting a panic! when the API is used incorrectly. Ideally, the API should be built so that there's no footguns on when this function is used.

Since the Frame trait is never used anywhere else, there's only penalty for its existence (confusing APIs), for no profit.

I propose we remove Frame trait and refactor the APIs of Sv2Frame and HandShakeFrame so they become more concise and intuitive.

code organization

impl blocks should be written immediately after the declaration of the respective struct or enum.

We should avoid mixing impl blocks for different entities together. If they need to co-exist in the same file, they should be grouped logically in different regions of the file, so the reader can easily find methods right next to the declaration of the struct or enum they belong to.

sv2_frame::get_header

note from @Fi3:

Note for the future, it could make sense to return a type that encode the above infos: enum Ok, Bigger, Smaller. This would be an API change so for now I would live it like it is

error handling and edge cases

• strict discipline over error handling (no unwrap, expect)
• strict discipline over edge cases (no unimplemented!, todo!, panic!, unreachable!, etc)