fixups for some doc comments

Author: folkertdev

libz-rs-sys/src/gz.rs

@@ -14,9 +14,11 @@ use zlib_rs::deflate::Strategy;
 use zlib_rs::MAX_WBITS;
 
 /// In the zlib C API, this structure exposes just enough of the internal state
-/// of an open gzFile to support the gzgetc() C macro. Since Rust code won't be
-/// using that C macro, we define gzFile_s as an empty structure. The first fields
-/// in GzState match what would be in the C version of gzFile_s.
+/// of an open [`gzFile`] to support the `gzgetc` C macro. Since Rust code won't be
+/// using that C macro, we define [`gzFile_s`] as an empty structure.
+// For ABI compatibility with zlib and zlib-ng, the first fields in [`GzState`] match
+// what would be in the C version of [`gzFile_s`]. But we don't want new users to rely
+// on this internal implementation, so the Rust [`gzFile_s`] is intentionally opaque.
 #[allow(non_camel_case_types)]
 pub enum gzFile_s {}
 
@@ -2156,7 +2158,7 @@ pub unsafe extern "C" fn gzputs(file: gzFile, s: *const c_char) -> c_int {
 
 /// Read one decompressed byte from `file`.
 ///
-/// Note: The C header file zlib.h provides a macro wrapper for gzgetc that implements
+/// Note: The C header file `zlib.h` provides a macro wrapper for `gzgetc` that implements
 /// the fast path inline and calls this function for the slow path.
 ///
 /// # Returns

zlib-rs/src/inflate/writer.rs

@@ -352,10 +352,9 @@ impl<'a> Writer<'a> {
         }
 
         // SAFETY: The caller ensured that src + length is within (or just at the end of)
-        // a readable range of bytes.
-        // FIXME: The other safety precondition for `add` is that the amount being added
-        // must fit in an `isize`. Should that be part of the documented safety preconditions
-        // for this function, so that our caller is responsible for ensuring it?
+        // a readable range of bytes. LLVM disallows allocations bigger than isize::MAX,
+        // so if src..src+length is a valid allocation (a precondition of this function)
+        // the length will never exceed isize::MAX.
         let end = unsafe { src.add(length) };
 
         // SAFETY: We checked above that length != 0, so there is at least one chunk remaining.