internals: Add docs to InputString

This commit is contained in:
Tobin C. Harding 2023-11-29 14:45:59 +11:00
parent fa8d3002cd
commit 4ecb1fe7da
No known key found for this signature in database
GPG Key ID: 40BF9E4C269D6607
1 changed files with 40 additions and 0 deletions

View File

@ -18,6 +18,28 @@ impl InputString {
/// Displays a message saying `failed to parse <self> as <what>`. /// Displays a message saying `failed to parse <self> as <what>`.
/// ///
/// This is normally used with the `write_err!` macro. /// This is normally used with the `write_err!` macro.
///
/// # Examples
///
/// ```
/// use core::fmt;
/// use bitcoin_internals::error::InputString;
/// use bitcoin_internals::write_err;
///
/// /// An example parsing error including the parse error from core.
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// pub struct ParseError {
/// input: InputString,
/// error: core::num::ParseIntError,
/// }
///
/// impl fmt::Display for ParseError {
/// fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
/// // Outputs "failed to parse '<input string>' as foo"
/// write_err!(f, "{}", self.input.display_cannot_parse("foo"); self.error)
/// }
/// }
/// ```
pub fn display_cannot_parse<'a, T>(&'a self, what: &'a T) -> CannotParse<'a, T> pub fn display_cannot_parse<'a, T>(&'a self, what: &'a T) -> CannotParse<'a, T>
where where
T: fmt::Display + ?Sized, T: fmt::Display + ?Sized,
@ -28,6 +50,24 @@ impl InputString {
/// Formats a message saying `<self> is not a known <what>`. /// Formats a message saying `<self> is not a known <what>`.
/// ///
/// This is normally used in leaf parse errors (with no source) when parsing an enum. /// This is normally used in leaf parse errors (with no source) when parsing an enum.
///
/// # Examples
///
/// ```
/// use core::fmt;
/// use bitcoin_internals::error::InputString;
///
/// /// An example parsing error.
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// pub struct ParseError(InputString);
///
/// impl fmt::Display for ParseError {
/// fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
/// // Outputs "'<input string>' is not a known foo"
/// self.0.unknown_variant("foo", f)
/// }
/// }
/// ```
pub fn unknown_variant<T>(&self, what: &T, f: &mut fmt::Formatter) -> fmt::Result pub fn unknown_variant<T>(&self, what: &T, f: &mut fmt::Formatter) -> fmt::Result
where where
T: fmt::Display + ?Sized, T: fmt::Display + ?Sized,