Merge pull request #114 from trifectatechfoundation/doc-link-fixes

update documentation

README.md

@@ -2,16 +2,19 @@
 
 [Documentation](https://docs.rs/bzip2)
 
-A streaming compression/decompression library for rust with bindings to libbz2.
+A streaming compression/decompression library for rust with bindings to `libbz2`.
 
-```toml
-# Cargo.toml
-[dependencies]
-bzip2 = "0.4"
-```
+## Features
 
+By default, `bzip2-rs` attempts to use the system `libbz2`. When `libbz2` is not available, the library 
+is built from source. A from source build requires a functional C toolchain for your target, and may not 
+work for all targets (in particular webassembly).
 
-# License
+*`static`*
+
+Always build `libbz2` from source, and statically link it. 
+
+## License
 
 This project is licensed under either of
 

src/bufread.rs

@@ -7,7 +7,7 @@ use crate::{Action, Compress, Compression, Decompress, Status};
 
 /// A bz2 encoder, or compressor.
 ///
-/// This structure implements a `BufRead` interface and will read uncompressed
+/// This structure implements a [`BufRead`] interface and will read uncompressed
 /// data from an underlying stream and emit a stream of compressed data.
 pub struct BzEncoder<R> {
     obj: R,
@@ -17,7 +17,7 @@ pub struct BzEncoder<R> {
 
 /// A bz2 decoder, or decompressor.
 ///
-/// This structure implements a `BufRead` interface and takes a stream of
+/// This structure implements a [`BufRead`] interface and takes a stream of
 /// compressed data as input, providing the decompressed data when read from.
 pub struct BzDecoder<R> {
     obj: R,
@@ -234,7 +234,7 @@ impl<W: Write> Write for BzDecoder<W> {
 /// A bzip2 streaming decoder that decodes all members of a multistream.
 ///
 /// Wikipedia, particularly, uses bzip2 multistream for their dumps, and the
-/// `pbzip2` tool creates such data as well;
+/// `pbzip2` tool creates such data as well.
 pub struct MultiBzDecoder<R>(BzDecoder<R>);
 
 impl<R: BufRead> MultiBzDecoder<R> {

src/lib.rs

@@ -1,18 +1,20 @@
 //! Bzip compression for Rust
 //!
-//! This library contains bindings to libbz2 to support bzip compression and
+//! This library contains bindings to [`libbz2`] to support bzip compression and
 //! decompression for Rust. The streams offered in this library are primarily
-//! found in the `reader` and `writer` modules. Both compressors and
+//! found in the [`mod@read`] and [`mod@write`] modules. Both compressors and
 //! decompressors are available in each module depending on what operation you
 //! need.
 //!
-//! Access to the raw decompression/compression stream is also provided through
-//! the `raw` module which has a much closer interface to libbz2.
+//! A more low-level interface, much closer to the interface of [`libbz2`], is
+//! available via the [`Compress`] and [`Decompress`] structs.
+//!
+//! [`libbz2`]: https://sourceware.org/bzip2/manual/manual.html
 //!
 //! # Example
 //!
 //! ```
-//! use std::io::prelude::*;
+//! use std::io::{BufRead, Read, Write};
 //! use bzip2::Compression;
 //! use bzip2::read::{BzEncoder, BzDecoder};
 //!
@@ -41,8 +43,8 @@
 //! `MultiBzDecoder`.
 //!
 //! All methods are internally capable of working with streams that may return
-//! `ErrorKind::WouldBlock` when they're not ready to perform the particular
-//! operation.
+//! [`ErrorKind::WouldBlock`](std::io::ErrorKind::WouldBlock) when they're not
+//! ready to perform the particular operation.
 //!
 //! Note that care needs to be taken when using these objects, however. The
 //! Tokio runtime, in particular, requires that data is fully flushed before

src/mem.rs

@@ -12,14 +12,14 @@ use crate::{ffi, Compression};
 
 /// Representation of an in-memory compression stream.
 ///
-/// An instance of `Compress` can be used to compress a stream of bz2 data.
+/// An instance of [`Compress`] can be used to compress a stream of bz2 data.
 pub struct Compress {
     inner: Stream<DirCompress>,
 }
 
 /// Representation of an in-memory decompression stream.
 ///
-/// An instance of `Decompress` can be used to inflate a stream of bz2-encoded
+/// An instance of [`Decompress`] can be used to decompress a stream of bz2-encoded
 /// data.
 pub struct Decompress {
     inner: Stream<DirDecompress>,
@@ -46,7 +46,7 @@ enum DirDecompress {}
 pub enum Action {
     /// Normal compression.
     Run = ffi::BZ_RUN as isize,
-    /// Request that the current compression block is terminate.
+    /// Flush any existing output, but do not read any more input
     Flush = ffi::BZ_FLUSH as isize,
     /// Request that the compression stream be finalized.
     Finish = ffi::BZ_FINISH as isize,
@@ -61,7 +61,7 @@ pub enum Status {
     /// The Flush action on a compression went ok.
     FlushOk,
 
-    /// THe Run action on compression went ok.
+    /// The Run action on compression went ok.
     RunOk,
 
     /// The Finish action on compression went ok.
@@ -135,8 +135,11 @@ impl Compress {
 
     /// Compress a block of input into a block of output.
     ///
-    /// If anything other than BZ_OK is seen, `Err` is returned. The action
-    /// given must be one of Run, Flush or Finish.
+    /// If anything other than [`BZ_OK`] is seen, `Err` is returned.
+    ///
+    /// The action given must be one of [`Action::Run`], [`Action::Flush`] or [`Action::Finish`].
+    ///
+    /// [`BZ_OK`]: ffi::BZ_OK
     pub fn compress(
         &mut self,
         input: &[u8],
@@ -209,7 +212,7 @@ impl Decompress {
     /// If `small` is true, then the library will use an alternative
     /// decompression algorithm which uses less memory but at the cost of
     /// decompressing more slowly (roughly speaking, half the speed, but the
-    /// maximum memory requirement drops to around 2300k). See
+    /// maximum memory requirement drops to around 2300k).
     pub fn new(small: bool) -> Decompress {
         unsafe {
             let mut raw = Box::new(mem::zeroed());

src/write.rs

@@ -64,12 +64,14 @@ impl<W: Write> BzEncoder<W> {
     ///
     /// Note that this function can only be used once data has finished being
     /// written to the output stream. After this function is called then further
-    /// calls to `write` may result in a panic.
+    /// calls to [`write`] may result in a panic.
     ///
     /// # Panics
     ///
     /// Attempts to write data to this stream may result in a panic after this
     /// function is called.
+    ///
+    /// [`write`]: Self::write
     pub fn try_finish(&mut self) -> io::Result<()> {
         while !self.done {
             self.dump()?;
@@ -89,9 +91,11 @@ impl<W: Write> BzEncoder<W> {
     ///
     /// Note that this function may not be suitable to call in a situation where
     /// the underlying stream is an asynchronous I/O stream. To finish a stream
-    /// the `try_finish` (or `shutdown`) method should be used instead. To
+    /// the [`try_finish`] (or `shutdown`) method should be used instead. To
     /// re-acquire ownership of a stream it is safe to call this method after
-    /// `try_finish` or `shutdown` has returned `Ok`.
+    /// [`try_finish`] or `shutdown` has returned `Ok`.
+    ///
+    /// [`try_finish`]: Self::try_finish
     pub fn finish(mut self) -> io::Result<W> {
         self.try_finish()?;
         Ok(self.obj.take().unwrap())
@@ -100,8 +104,11 @@ impl<W: Write> BzEncoder<W> {
     /// Returns the number of bytes produced by the compressor
     ///
     /// Note that, due to buffering, this only bears any relation to
-    /// `total_in()` after a call to `flush()`.  At that point,
+    /// [`total_in`] after a call to [`flush`].  At that point,
     /// `total_out() / total_in()` is the compression ratio.
+    ///
+    /// [`flush`]: Self::flush
+    /// [`total_in`]: Self::total_in
     pub fn total_out(&self) -> u64 {
         self.data.total_out()
     }
@@ -187,12 +194,14 @@ impl<W: Write> BzDecoder<W> {
     ///
     /// Note that this function can only be used once data has finished being
     /// written to the output stream. After this function is called then further
-    /// calls to `write` may result in a panic.
+    /// calls to [`write`] may result in a panic.
     ///
     /// # Panics
     ///
     /// Attempts to write data to this stream may result in a panic after this
     /// function is called.
+    ///
+    /// [`write`]: Self::write
     pub fn try_finish(&mut self) -> io::Result<()> {
         while !self.done {
             let _ = self.write(&[])?;
@@ -204,9 +213,11 @@ impl<W: Write> BzDecoder<W> {
     ///
     /// Note that this function may not be suitable to call in a situation where
     /// the underlying stream is an asynchronous I/O stream. To finish a stream
-    /// the `try_finish` (or `shutdown`) method should be used instead. To
+    /// the [`try_finish`] (or `shutdown`) method should be used instead. To
     /// re-acquire ownership of a stream it is safe to call this method after
-    /// `try_finish` or `shutdown` has returned `Ok`.
+    /// [`try_finish`] or `shutdown` has returned `Ok`.
+    ///
+    /// [`try_finish`]: Self::try_finish
     pub fn finish(&mut self) -> io::Result<W> {
         self.try_finish()?;
         Ok(self.obj.take().unwrap())
@@ -215,8 +226,11 @@ impl<W: Write> BzDecoder<W> {
     /// Returns the number of bytes produced by the decompressor
     ///
     /// Note that, due to buffering, this only bears any relation to
-    /// `total_in()` after a call to `flush()`.  At that point,
+    /// [`total_in`] after a call to [`flush`].  At that point,
     /// `total_in() / total_out()` is the compression ratio.
+    ///
+    /// [`flush`]: Self::flush
+    /// [`total_in`]: Self::total_in
     pub fn total_out(&self) -> u64 {
         self.data.total_out()
     }