zcash_address: Add ZcashAddress::try_from_encoded method

This places parsing documentation front and centre, while also making
it clear that `str::parse` is the anticipated main entry point.

components/zcash_address/src/encoding.rs

@@ -33,6 +33,7 @@ impl Error for ParseError {}
 impl FromStr for ZcashAddress {
     type Err = ParseError;
 
+    /// Attempts to parse the given string as a Zcash address.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         // Remove leading and trailing whitespace, to handle copy-paste errors.
         let s = s.trim();

components/zcash_address/src/lib.rs

@@ -35,3 +35,39 @@ enum AddressKind {
     P2pkh(kind::p2pkh::Data),
     P2sh(kind::p2sh::Data),
 }
+
+impl ZcashAddress {
+    /// Attempts to parse the given string as a Zcash address.
+    ///
+    /// This simply calls [`s.parse()`], leveraging the [`FromStr` implementation].
+    ///
+    /// [`s.parse()`]: std::primitive::str::parse
+    /// [`FromStr` implementation]: ZcashAddress#impl-FromStr
+    ///
+    /// # Errors
+    ///
+    /// In most cases, [`ParseError::NotZcash`] will be returned on failure. The two
+    /// exceptions are:
+    ///
+    /// - If the parser can detect that the string _must_ contain an address encoding used
+    ///   by Zcash, [`ParseError::InvalidEncoding`] will be returned if any subsequent
+    ///   part of that encoding is invalid.
+    ///
+    /// - [`ParseError::MaybeZcash`] will be returned if the string is Bech32-encoded data
+    ///   that satisfies some heuristics for probable future Zcash address formats (such
+    ///   as beginning with a `z`). This can either be treated as an indication that this
+    ///   library dependency should be updated, or mapped to [`ParseError::NotZcash`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use zcash_address::ZcashAddress;
+    ///
+    /// let encoded = "zs1z7rejlpsa98s2rrrfkwmaxu53e4ue0ulcrw0h4x5g8jl04tak0d3mm47vdtahatqrlkngh9sly";
+    /// let addr = ZcashAddress::try_from_encoded(&encoded);
+    /// assert_eq!(encoded.parse(), addr);
+    /// ```
+    pub fn try_from_encoded(s: &str) -> Result<Self, ParseError> {
+        s.parse()
+    }
+}