Repository: BurntSushi/byteorder (language: rust)

Issue:
Put panic and error docs in "Panics" and "Errors" sections
Write now information about panic and error conditions is written inline with the main text. Per conventions they should be in sections titled "Panics" and "Errors".


Discussion / hints:

Fix patch:
diff --git a/Cargo.toml b/Cargo.toml
index d207d47..95f8daa 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "byteorder"
+# NB: When modifying, also modify html_root_url in lib.rs
 version = "1.0.0"  #:version
 authors = ["Andrew Gallant <jamslam@gmail.com>"]
 description = "Library for reading/writing numbers in big-endian and little-endian."
diff --git a/src/lib.rs b/src/lib.rs
index e524560..035aca6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -38,6 +38,7 @@ assert_eq!(wtr, vec![5, 2, 0, 3]);
 
 #![deny(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
+#![doc(html_root_url = "https://docs.rs/byteorder/1.0.0")]
 
 #[cfg(feature = "std")]
 extern crate core;
@@ -120,48 +121,66 @@ pub trait ByteOrder
     : Clone + Copy + Debug + Default + Eq + Hash + Ord + PartialEq + PartialOrd {
     /// Reads an unsigned 16 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 2`.
     fn read_u16(buf: &[u8]) -> u16;
 
     /// Reads an unsigned 32 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     fn read_u32(buf: &[u8]) -> u32;
 
     /// Reads an unsigned 64 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     fn read_u64(buf: &[u8]) -> u64;
 
     /// Reads an unsigned n-bytes integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `nbytes < 1` or `nbytes > 8` or
     /// `buf.len() < nbytes`
     fn read_uint(buf: &[u8], nbytes: usize) -> u64;
 
     /// Writes an unsigned 16 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 2`.
     fn write_u16(buf: &mut [u8], n: u16);
 
     /// Writes an unsigned 32 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     fn write_u32(buf: &mut [u8], n: u32);
 
     /// Writes an unsigned 64 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     fn write_u64(buf: &mut [u8], n: u64);
 
     /// Writes an unsigned integer `n` to `buf` using only `nbytes`.
     ///
+    /// # Panics
+    ///
     /// If `n` is not representable in `nbytes`, or if `nbytes` is `> 8`, then
     /// this method panics.
     fn write_uint(buf: &mut [u8], n: u64, nbytes: usize);
 
     /// Reads a signed 16 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 2`.
     #[inline]
     fn read_i16(buf: &[u8]) -> i16 {
@@ -170,6 +189,8 @@ pub trait ByteOrder
 
     /// Reads a signed 32 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     #[inline]
     fn read_i32(buf: &[u8]) -> i32 {
@@ -178,6 +199,8 @@ pub trait ByteOrder
 
     /// Reads a signed 64 bit integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     #[inline]
     fn read_i64(buf: &[u8]) -> i64 {
@@ -186,6 +209,8 @@ pub trait ByteOrder
 
     /// Reads a signed n-bytes integer from `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `nbytes < 1` or `nbytes > 8` or
     /// `buf.len() < nbytes`
     #[inline]
@@ -195,6 +220,8 @@ pub trait ByteOrder
 
     /// Reads a IEEE754 single-precision (4 bytes) floating point number.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     #[inline]
     fn read_f32(buf: &[u8]) -> f32 {
@@ -203,6 +230,8 @@ pub trait ByteOrder
 
     /// Reads a IEEE754 double-precision (8 bytes) floating point number.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     #[inline]
     fn read_f64(buf: &[u8]) -> f64 {
@@ -211,6 +240,8 @@ pub trait ByteOrder
 
     /// Writes a signed 16 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 2`.
     #[inline]
     fn write_i16(buf: &mut [u8], n: i16) {
@@ -219,6 +250,8 @@ pub trait ByteOrder
 
     /// Writes a signed 32 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     #[inline]
     fn write_i32(buf: &mut [u8], n: i32) {
@@ -227,6 +260,8 @@ pub trait ByteOrder
 
     /// Writes a signed 64 bit integer `n` to `buf`.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     #[inline]
     fn write_i64(buf: &mut [u8], n: i64) {
@@ -235,6 +270,8 @@ pub trait ByteOrder
 
     /// Writes a signed integer `n` to `buf` using only `nbytes`.
     ///
+    /// # Panics
+    ///
     /// If `n` is not representable in `nbytes`, or if `nbytes` is `> 8`, then
     /// this method panics.
     #[inline]
@@ -244,6 +281,8 @@ pub trait ByteOrder
 
     /// Writes a IEEE754 single-precision (4 bytes) floating point number.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 4`.
     #[inline]
     fn write_f32(buf: &mut [u8], n: f32) {
@@ -252,6 +291,8 @@ pub trait ByteOrder
 
     /// Writes a IEEE754 double-precision (8 bytes) floating point number.
     ///
+    /// # Panics
+    ///
     /// Panics when `buf.len() < 8`.
     #[inline]
     fn write_f64(buf: &mut [u8], n: f64) {
@@ -268,7 +309,7 @@ pub enum BigEndian {}
 
 impl Default for BigEndian {
     fn default() -> BigEndian {
-        unreachable!()
+        panic!("BigEndian default")
     }
 }
 
@@ -281,7 +322,7 @@ pub enum LittleEndian {}
 
 impl Default for LittleEndian {
     fn default() -> LittleEndian {
-        unreachable!()
+        panic!("LittleEndian default")
     }
 }
 
diff --git a/src/new.rs b/src/new.rs
index b5f3770..79ef5fd 100644
--- a/src/new.rs
+++ b/src/new.rs
@@ -25,6 +25,12 @@ pub trait ReadBytesExt: io::Read {
     ///
     /// Note that since this reads a single byte, no byte order conversions
     /// are used. It is included for completeness.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_u8(&mut self) -> Result<u8> {
         let mut buf = [0; 1];
@@ -36,6 +42,12 @@ pub trait ReadBytesExt: io::Read {
     ///
     /// Note that since this reads a single byte, no byte order conversions
     /// are used. It is included for completeness.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_i8(&mut self) -> Result<i8> {
         let mut buf = [0; 1];
@@ -44,6 +56,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads an unsigned 16 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_u16<T: ByteOrder>(&mut self) -> Result<u16> {
         let mut buf = [0; 2];
@@ -52,6 +70,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads a signed 16 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_i16<T: ByteOrder>(&mut self) -> Result<i16> {
         let mut buf = [0; 2];
@@ -60,6 +84,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads an unsigned 32 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_u32<T: ByteOrder>(&mut self) -> Result<u32> {
         let mut buf = [0; 4];
@@ -68,6 +98,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads a signed 32 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_i32<T: ByteOrder>(&mut self) -> Result<i32> {
         let mut buf = [0; 4];
@@ -76,6 +112,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads an unsigned 64 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_u64<T: ByteOrder>(&mut self) -> Result<u64> {
         let mut buf = [0; 8];
@@ -84,6 +126,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads a signed 64 bit integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_i64<T: ByteOrder>(&mut self) -> Result<i64> {
         let mut buf = [0; 8];
@@ -92,6 +140,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads an unsigned n-bytes integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_uint<T: ByteOrder>(&mut self, nbytes: usize) -> Result<u64> {
         let mut buf = [0; 8];
@@ -100,6 +154,12 @@ pub trait ReadBytesExt: io::Read {
     }
 
     /// Reads a signed n-bytes integer from the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_int<T: ByteOrder>(&mut self, nbytes: usize) -> Result<i64> {
         let mut buf = [0; 8];
@@ -109,6 +169,12 @@ pub trait ReadBytesExt: io::Read {
 
     /// Reads a IEEE754 single-precision (4 bytes) floating point number from
     /// the underlying reader.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     #[inline]
     fn read_f32<T: ByteOrder>(&mut self) -> Result<f32> {
         let mut buf = [0; 4];
@@ -119,6 +185,12 @@ pub trait ReadBytesExt: io::Read {
     /// Reads a IEEE754 double-precision (8 bytes) floating point number from
     /// the underlying reader.
     #[inline]
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
     fn read_f64<T: ByteOrder>(&mut self) -> Result<f64> {
         let mut buf = [0; 8];
         try!(self.read_exact(&mut buf));
@@ -153,6 +225,12 @@ pub trait WriteBytesExt: io::Write {
     ///
     /// Note that since this writes a single byte, no byte order conversions
     /// are used. It is included for completeness.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_u8(&mut self, n: u8) -> Result<()> {
         self.write_all(&[n])
@@ -162,12 +240,24 @@ pub trait WriteBytesExt: io::Write {
     ///
     /// Note that since this writes a single byte, no byte order conversions
     /// are used. It is included for completeness.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_i8(&mut self, n: i8) -> Result<()> {
         self.write_all(&[n as u8])
     }
 
     /// Writes an unsigned 16 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_u16<T: ByteOrder>(&mut self, n: u16) -> Result<()> {
         let mut buf = [0; 2];
@@ -176,6 +266,12 @@ pub trait WriteBytesExt: io::Write {
     }
 
     /// Writes a signed 16 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_i16<T: ByteOrder>(&mut self, n: i16) -> Result<()> {
         let mut buf = [0; 2];
@@ -184,6 +280,12 @@ pub trait WriteBytesExt: io::Write {
     }
 
     /// Writes an unsigned 32 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_u32<T: ByteOrder>(&mut self, n: u32) -> Result<()> {
         let mut buf = [0; 4];
@@ -192,6 +294,12 @@ pub trait WriteBytesExt: io::Write {
     }
 
     /// Writes a signed 32 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_i32<T: ByteOrder>(&mut self, n: i32) -> Result<()> {
         let mut buf = [0; 4];
@@ -200,6 +308,12 @@ pub trait WriteBytesExt: io::Write {
     }
 
     /// Writes an unsigned 64 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_u64<T: ByteOrder>(&mut self, n: u64) -> Result<()> {
         let mut buf = [0; 8];
@@ -208,6 +322,12 @@ pub trait WriteBytesExt: io::Write {
     }
 
     /// Writes a signed 64 bit integer to the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_i64<T: ByteOrder>(&mut self, n: i64) -> Result<()> {
         let mut buf = [0; 8];
@@ -217,6 +337,14 @@ pub trait WriteBytesExt: io::Write {
 
     /// Writes an unsigned n-bytes integer to the underlying writer.
     ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Panics
+    ///
     /// If the given integer is not representable in the given number of bytes,
     /// this method panics. If `nbytes > 8`, this method panics.
     #[inline]
@@ -232,6 +360,14 @@ pub trait WriteBytesExt: io::Write {
 
     /// Writes a signed n-bytes integer to the underlying writer.
     ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Panics
+    ///
     /// If the given integer is not representable in the given number of bytes,
     /// this method panics. If `nbytes > 8`, this method panics.
     #[inline]
@@ -247,6 +383,12 @@ pub trait WriteBytesExt: io::Write {
 
     /// Writes a IEEE754 single-precision (4 bytes) floating point number to
     /// the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
     #[inline]
     fn write_f32<T: ByteOrder>(&mut self, n: f32) -> Result<()> {
         let mut buf = [0; 4];


Test patch: