Add and update documentation

tormol · tormol · commit a9773b112cf5 · 2016-08-14T23:53:14.000+02:00
diff --git a/README.md b/README.md
@@ -8,9 +8,13 @@ Types and conversion traits are described in the
 
 # Using ascii without libstd
 
-Most of `AsciiChar` and `AsciiStr` can be used without `std` by enabling the feature `no_std`. The
-owned string type `AsciiString` and the conversion trait `IntoAsciiString` as well as all methods
-referring to these types aren't available without `std`.
+Most of `AsciiChar` and `AsciiStr` can be used without `std` by enabling the feature `no_std`.  
+The owned string type `AsciiString` and the conversion trait `IntoAsciiString` as well as all methods referring to these types are unavailable.  
+Because libcore doesn't have `AsciiExt` and `Error`, most of their methods are implemented directly:
+* `Ascii{Char,Str}::eq_ignore_ascii_case()`
+* `AsciiChar::to_ascii_{upper,lower}case()`
+* `AsciiStr::make_ascii_{upper,lower}case()`
+* `{ToAsciiChar,AsAsciiStr}Error::description()`
 
 # Requirements
 
diff --git a/RELEASES.md b/RELEASES.md
@@ -1,9 +1,14 @@
 Unreleased
 ==========
 * Return `FromAsciiError` instead of the input when `AsciiString::from_ascii()` or `into_ascii_string()` fails.
+* Fix `AsciiChar::to_ascii_lowercase()` converting to uppercase. (introduced by 0.7.0)
 * Make `AsciiChar` comparable with `char` and `u8`.
 * Add `AsciiChar::as_printable_char()` and the free functions `caret_encode()` and `caret_decode()`.
-* Fix the implementation of `AsciiExt::to_ascii_lowercase()` for `AsciiChar` converting to uppercase. (introduced in 0.7.0)
+* Implement some methods from `AsciiExt` and `Error` (which are not in libcore) directly in `no_std` mode:
+  * `Ascii{Char,Str}::eq_ignore_ascii_case()`
+  * `AsciiChar::to_ascii_{upper,lower}case()`
+  * `AsciiStr::make_ascii_{upper,lower}case()`
+  * `{ToAsciiChar,AsAsciiStr}Error::description()`
 
 Version 0.7.0 (2016-06-25)
 ==========================
diff --git a/src/ascii_char.rs b/src/ascii_char.rs
@@ -474,6 +474,9 @@ impl AsciiChar {
     }
 
     #[cfg(feature = "no_std")]
+    /// Maps letters `a`...`z` to `A`...`Z` and returns everything else unchanged.
+    ///
+    /// A replacement for `AsciiExt::to_ascii_uppercase()`.
     pub fn to_ascii_uppercase(&self) -> Self {
         unsafe{ match *self as u8 {
             b'a'...b'z' => AsciiChar::from_unchecked(self.as_byte() - (b'a' - b'A')),
@@ -482,6 +485,9 @@ impl AsciiChar {
     }
 
     #[cfg(feature = "no_std")]
+    /// Maps letters `A`...`Z` to `a`...`z` and returns everything else unchanged.
+    ///
+    /// A replacement for `AsciiExt::to_ascii_lowercase()`.
     pub fn to_ascii_lowercase(&self) -> Self {
         unsafe{ match *self as u8 {
             b'A'...b'Z' => AsciiChar::from_unchecked(self.as_byte() + (b'a' - b'A')),
@@ -490,6 +496,9 @@ impl AsciiChar {
     }
 
     #[cfg(feature = "no_std")]
+    /// Compares two characters case-insensitively.
+    ///
+    /// A replacement for `AsciiExt::eq_ignore_ascii_case()`.
     pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool {
         self.to_ascii_lowercase() == other.to_ascii_lowercase()
     }
@@ -578,6 +587,7 @@ const ERRORMSG_CHAR: &'static str = "not an ASCII character";
 
 #[cfg(feature = "no_std")]
 impl ToAsciiCharError {
+    /// Returns a description for this error, like `std::error::Error::description`.
     pub fn description(&self) -> &'static str {
         ERRORMSG_CHAR
     }
diff --git a/src/ascii_str.rs b/src/ascii_str.rs
@@ -168,19 +168,28 @@ impl AsciiStr {
     }
 
     #[cfg(feature = "no_std")]
+    /// Compares two strings case-insensitively.
+    ///
+    /// A replacement for `AsciiExt::eq_ignore_ascii_case()`.
     pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool {
         self.len() == other.len() &&
         self.slice.iter().zip(other.slice.iter()).all(|(a, b)| a.eq_ignore_ascii_case(b) )
     }
 
     #[cfg(feature = "no_std")]
+    /// Replaces lowercase letters with their uppercase equivalent.
+    ///
+    /// A replacement for `AsciiExt::make_ascii_uppercase()`.
     pub fn make_ascii_uppercase(&mut self) {
         for a in &mut self.slice {
             *a = a.to_ascii_uppercase();
         }
     }
 
     #[cfg(feature = "no_std")]
+    /// Replaces uppercase letters with their lowercase equivalent.
+    ///
+    /// A replacement for `AsciiExt::make_ascii_lowercase()`.
     pub fn make_ascii_lowercase(&mut self) {
         for a in &mut self.slice {
             *a = a.to_ascii_lowercase();
@@ -370,6 +379,7 @@ impl AsAsciiStrError {
         self.0
     }
     #[cfg(feature = "no_std")]
+    /// Returns a description for this error, like `std::error::Error::description`.
     pub fn description(&self) -> &'static str {
         ERRORMSG_STR
     }
@@ -381,7 +391,6 @@ impl fmt::Display for AsAsciiStrError {
 }
 #[cfg(not(feature = "no_std"))]
 impl Error for AsAsciiStrError {
-    /// Returns "one or more bytes are not ASCII"
     fn description(&self) -> &'static str {
         ERRORMSG_STR
     }

Original file line number	Diff line number	Diff line change
`@@ -168,19 +168,28 @@ impl AsciiStr {`
`168`	`168`	`}`
`169`	`169`
`170`	`170`	`#[cfg(feature = "no_std")]`
	`171`	`+ /// Compares two strings case-insensitively.`
	`172`	`+ ///`
	`173`	+ /// A replacement for `AsciiExt::eq_ignore_ascii_case()`.
`171`	`174`	`pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool {`
`172`	`175`	`self.len() == other.len() &&`
`173`	`176`	`self.slice.iter().zip(other.slice.iter()).all(\|(a, b)\| a.eq_ignore_ascii_case(b) )`
`174`	`177`	`}`
`175`	`178`
`176`	`179`	`#[cfg(feature = "no_std")]`
	`180`	`+ /// Replaces lowercase letters with their uppercase equivalent.`
	`181`	`+ ///`
	`182`	+ /// A replacement for `AsciiExt::make_ascii_uppercase()`.
`177`	`183`	`pub fn make_ascii_uppercase(&mut self) {`
`178`	`184`	`for a in &mut self.slice {`
`179`	`185`	`*a = a.to_ascii_uppercase();`
`180`	`186`	`}`
`181`	`187`	`}`
`182`	`188`
`183`	`189`	`#[cfg(feature = "no_std")]`
	`190`	`+ /// Replaces uppercase letters with their lowercase equivalent.`
	`191`	`+ ///`
	`192`	+ /// A replacement for `AsciiExt::make_ascii_lowercase()`.
`184`	`193`	`pub fn make_ascii_lowercase(&mut self) {`
`185`	`194`	`for a in &mut self.slice {`
`186`	`195`	`*a = a.to_ascii_lowercase();`
`@@ -370,6 +379,7 @@ impl AsAsciiStrError {`
`370`	`379`	`self.0`
`371`	`380`	`}`
`372`	`381`	`#[cfg(feature = "no_std")]`
	`382`	+ /// Returns a description for this error, like `std::error::Error::description`.
`373`	`383`	`pub fn description(&self) -> &'static str {`
`374`	`384`	`ERRORMSG_STR`
`375`	`385`	`}`
`@@ -381,7 +391,6 @@ impl fmt::Display for AsAsciiStrError {`
`381`	`391`	`}`
`382`	`392`	`#[cfg(not(feature = "no_std"))]`
`383`	`393`	`impl Error for AsAsciiStrError {`
`384`		`- /// Returns "one or more bytes are not ASCII"`
`385`	`394`	`fn description(&self) -> &'static str {`
`386`	`395`	`ERRORMSG_STR`
`387`	`396`	`}`