docs fixes

Author: glebpom

src/error.rs

@@ -137,11 +137,13 @@ impl From<std::convert::Infallible> for Error {
     }
 }
 
+/// Error returned when max capacity of `HeaderMap` is exceeded
 pub struct CapacityOverflow {
     _priv: (),
 }
 
 impl CapacityOverflow {
+    /// Create new `CapacityOverflow` instance
     pub fn new() -> CapacityOverflow {
         CapacityOverflow { _priv: () }
     }

src/header/map.rs

@@ -1081,12 +1081,31 @@ impl<T> HeaderMap<T> {
     /// Gets the given key's corresponding entry in the map for in-place
     /// manipulation.
     ///
-    /// # Errors
+    /// # Panics
     ///
-    /// This method differs from `entry` by allowing types that may not be
-    /// valid `HeaderName`s to passed as the key (such as `String`). If they
-    /// do not parse as a valid `HeaderName`, this returns an
-    /// `InvalidHeaderName` error.
+    /// This method panics if capacity exceeds max `HeaderMap` capacity
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::HeaderMap;
+    /// let mut map: HeaderMap<u32> = HeaderMap::default();
+    ///
+    /// let headers = &[
+    ///     "content-length",
+    ///     "x-hello",
+    ///     "Content-Length",
+    ///     "x-world",
+    /// ];
+    ///
+    /// for &header in headers {
+    ///     let counter = map.entry(header).or_insert(0);
+    ///     *counter += 1;
+    /// }
+    ///
+    /// assert_eq!(map["content-length"], 2);
+    /// assert_eq!(map["x-hello"], 1);
+    /// ```
     pub fn entry<K>(&mut self, key: K) -> Entry<'_, T>
         where
             K: IntoHeaderName,
@@ -1103,6 +1122,9 @@ impl<T> HeaderMap<T> {
     /// valid `HeaderName`s to passed as the key (such as `String`). If they
     /// do not parse as a valid `HeaderName`, this returns an
     /// `InvalidHeaderName` error.
+    ///
+    /// It may return `CapacityOverflow` error if size exceeds the maximum
+    /// `HeaderMap` capacity
     pub fn try_entry<K>(&mut self, key: K) -> Result<Entry<'_, T>, Error>
     where
         K: AsHeaderName,
@@ -1162,16 +1184,20 @@ impl<T> HeaderMap<T> {
     /// The key is not updated, though; this matters for types that can be `==`
     /// without being identical.
     ///
+    /// # Panics
+    ///
+    /// This method panics if capacity exceeds max `HeaderMap` capacity
+    ///
     /// # Examples
     ///
     /// ```
     /// # use http::HeaderMap;
     /// # use http::header::HOST;
     /// let mut map = HeaderMap::new();
-    /// assert!(map.try_insert(HOST, "world".parse().unwrap()).unwrap().is_none());
+    /// assert!(map.insert(HOST, "world".parse().unwrap()).is_none());
     /// assert!(!map.is_empty());
     ///
-    /// let mut prev = map.try_insert(HOST, "earth".parse().unwrap()).unwrap().unwrap();
+    /// let mut prev = map.insert(HOST, "earth".parse().unwrap()).unwrap();
     /// assert_eq!("world", prev);
     /// ```
     pub fn insert<K>(&mut self, key: K, val: T) -> Option<T>
@@ -1295,16 +1321,20 @@ impl<T> HeaderMap<T> {
     /// updated, though; this matters for types that can be `==` without being
     /// identical.
     ///
+    /// # Panics
+    ///
+    /// This method panics if capacity exceeds max `HeaderMap` capacity
+    ///
     /// # Examples
     ///
     /// ```
     /// # use http::HeaderMap;
     /// # use http::header::HOST;
     /// let mut map = HeaderMap::new();
-    /// assert!(map.try_insert(HOST, "world".parse().unwrap()).unwrap().is_none());
+    /// assert!(map.insert(HOST, "world".parse().unwrap()).is_none());
     /// assert!(!map.is_empty());
     ///
-    /// map.try_append(HOST, "earth".parse().unwrap()).unwrap();
+    /// map.append(HOST, "earth".parse().unwrap());
     ///
     /// let values = map.get_all("host");
     /// let mut i = values.iter();

src/lib.rs

@@ -158,7 +158,7 @@
 //! assert_eq!(uri.query(), None);
 //! ```
 
-#![deny(warnings, missing_debug_implementations)]
+#![deny(warnings, missing_docs, missing_debug_implementations)]
 
 #[cfg(test)]
 #[macro_use]