search

memorysafety / zlib-rs

A safer zlib
zlib License
75 stars 6 forks source link

rustdoc comments? #102

Open cpu opened 1 month ago

cpu commented 1 month ago

Hi there,

I noticed while reviewing some code using zlib-rs that most (all?) functions in https://docs.rs/zlib-rs/latest/zlib_rs/ are uncommented. (Examples: compress_bound, ReturnCode, uncompress_slice, etc).

Is this because the API is still considered unstable, or is the intent that users read the zlib manual? Would PRs adding rustdoc comments be accepted or is it too soon?

Thanks!

folkertdev commented 1 month ago

The status of the zlib-rs crate is weird because, for rust users the flate2 interface is much nicer and probably what they are already using, and for C (or other FFI) users the libz-rs-sys crate is the relevant api.

Because the libz-rs-sys api is determined by zlib itself and won't change, I think there we're absolutely ready to properly document behavior and safety assumptions. This will be based on the zlib manual but I think we can do better than that page (e.g. because we get to use markdown and can cross-link definitions).

For zlib-rs itself it is early, but on the other hand core pieces of functionality won't change drastically at this point.

So, I guess, go for it? with the knowledge that we may slightly tweak or move around certain definitions.

cpu commented 1 month ago

Makes sense :+1: Thanks for the quick reply.

For rust users the flate2 interface is much nicer and probably what they are already using

I think the context that had me looking at this might be a rare case where flate2 is too generic and we do want to be using zlib-rs directly (https://github.com/rustls/rustls/pull/1966).