Improve Documentation

[Plecra]

#24 (comment)

The lack of documentation for the default::core API is proving quite painful for me while using it. Due to the complexity of the library, I think this is relatively high priority and it would be good to at least give an explanation of the error and flush states.

I'll likely create a PR once I'm confident I have a grasp on the functions I'm working with. It'd also be handy if you could share summaries of each API's purpose

[oyvindln]

Yup. I am looking for suggestions for a V2 low-level API, as the current one is just some glue code we used to transition the flate2 backend from calling via rust instead of C calls.

[fullermd]

In a little consideration of using this (in place of flate2, which also has very scarce documentation on incremental API usage), I definitely hit this hard. I've made some attempt in PR #108 to try and fill in some of the blanks, but no guarantees I didn't confuse things even more from lack of understanding!

(I mean, I know C, and I'm passable at Rust, but reading intricate dense C written in Rust is a whole 'nother skillset ;)