DOC: Promise debug assertions for unsafe methods

Instead of being vague about it, we can promise it.

We continue to be a bit vague in ArrayString::set_len.  I don't see how
to add a char boundary check in ArrayString::set_len unfortunately.

It's a tricky issue, checking char boundaries requires reading the
memory of the string, and we don't even know if the user of set_len has
initialized that area of memory yet (but they hopefully did).

src/array_string.rs

@@ -322,10 +322,11 @@ impl<A: Array<Item=u8>> ArrayString<A> {
 
     /// Set the strings's length.
     ///
-    /// May panic if `length` is greater than the capacity.
-    ///
     /// This function is `unsafe` because it changes the notion of the
     /// number of “valid” bytes in the string. Use with care.
+    ///
+    /// This method uses *debug assertions* to check the validity of `length`
+    /// and may use other debug assertions.
     #[inline]
     pub unsafe fn set_len(&mut self, length: usize) {
         debug_assert!(length <= self.capacity());

src/lib.rs

@@ -226,7 +226,7 @@ impl<A: Array> ArrayVec<A> {
     /// It is up to the caller to ensure the capacity of the vector is
     /// sufficiently large.
     ///
-    /// This method *may* use debug assertions to check that the arrayvec is not full.
+    /// This method uses *debug assertions* to check that the arrayvec is not full.
     ///
     /// ```
     /// use arrayvec::ArrayVec;
@@ -502,11 +502,11 @@ impl<A: Array> ArrayVec<A> {
 
     /// Set the vector's length without dropping or moving out elements
     ///
-    /// May use debug assertions to check that `length` is not greater than the
+    /// This method is `unsafe` because it changes the notion of the
-    /// capacity.
-    ///
-    /// This function is `unsafe` because it changes the notion of the
     /// number of “valid” elements in the vector. Use with care.
+    ///
+    /// This method uses *debug assertions* to check that check that `length` is
+    /// not greater than the capacity.
     #[inline]
     pub unsafe fn set_len(&mut self, length: usize) {
         debug_assert!(length <= self.capacity());