From 325fb915f09a248a9b907bd1fac459ff0d50744c Mon Sep 17 00:00:00 2001
From: Paul Spooren <mail@aparcar.org>
Date: Wed, 6 Nov 2024 17:41:47 +0100
Subject: [PATCH] docs(result): add docstring and examples

Signed-off-by: Paul Spooren <mail@aparcar.org>
---
 util/src/result.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/util/src/result.rs b/util/src/result.rs
index 041adbd..727db93 100644
--- a/util/src/result.rs
+++ b/util/src/result.rs
@@ -125,6 +125,18 @@ impl<T> GuaranteedValue for Guaranteed<T> {
     }
 }
 
+/// Checks a condition is true and returns an error if not.
+///
+/// # Examples
+///
+/// ```rust
+/// # use rosenpass_util::result::ensure_or;
+/// let result = ensure_or(5 > 3, "not greater");
+/// assert!(result.is_ok());
+///
+/// let result = ensure_or(5 < 3, "not less");
+/// assert!(result.is_err());
+/// ```
 pub fn ensure_or<E>(b: bool, err: E) -> Result<(), E> {
     match b {
         true => Ok(()),
@@ -132,6 +144,18 @@ pub fn ensure_or<E>(b: bool, err: E) -> Result<(), E> {
     }
 }
 
+/// Evaluates to an error if the condition is true.
+///
+/// # Examples
+///
+/// ```rust
+/// # use rosenpass_util::result::bail_if;
+/// let result = bail_if(false, "not bailed");
+/// assert!(result.is_ok());
+///
+/// let result = bail_if(true, "bailed");
+/// assert!(result.is_err());
+/// ```
 pub fn bail_if<E>(b: bool, err: E) -> Result<(), E> {
     ensure_or(!b, err)
 }