From 294b788942b5f53857f1769342e7899ee5c6201d Mon Sep 17 00:00:00 2001
From: myrkle11 <54760496+myrkle11@users.noreply.github.com>
Date: Sun, 23 Aug 2026 15:30:39 -0700
Subject: [PATCH] Update etl::expected documentation (#1564)

* Update _index.md

* Update _index.md

* Cherry pick the Docker fixes for PowerPC (#1563)

Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.com>

* Update expected documentation to reflect the current state of the code

* Fix code blocks for expected class section

* Change wording slightly

* make changes ala coderabbitai

* Fixed typos

---------

Co-authored-by: John Wellbelove <jwellbelove@users.noreply.github.com>
Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.com>
---
 docs/utilities/expected.md | 446 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 438 insertions(+), 8 deletions(-)

diff --git a/docs/utilities/expected.md b/docs/utilities/expected.md
index f6cbcd63..8443a782 100644
--- a/docs/utilities/expected.md
+++ b/docs/utilities/expected.md
@@ -192,13 +192,13 @@ Swap with another etl::unexpected
 ```cpp
 template <typename TValue, typename TError>
 class expected
-```cpp
+```
 
 Specialisation for void value type.
 ```cpp
 template <typename TError>
 class expected<void, TError>
-```cpp
+```
 
 ### Types
 
@@ -421,6 +421,7 @@ value_type& value() const
 Get the value.
 Undefined if has_value() returns false.
 Not valid for void specialisation.
+Before: C++11
 
 ---
 
@@ -536,13 +537,46 @@ Before: C++11
 
 ---
 
+```cpp
+template <typename G>
+ETL_NODISCARD
+ETL_CONSTEXPR14
+error_type error_or(G&& default_error) const&
+```
+**Description**
+Returns default_error if has_value() returns true; otherwise returns the stored error.
+Since: C++11
+
+---
+
+```cpp
+template <typename G>
+ETL_NODISCARD
+ETL_CONSTEXPR14
+error_type error_or(G&& default_error)&&
+```
+**Description**
+Returns default_error if has_value() returns true; otherwise returns the stored error.
+Since: C++11
+
+---
+
+```cpp
+template <typename G>
+error_type error_or(const G& default_error) const
+```
+**Description**
+Returns default_error if has_value() returns true; otherwise returns the stored error.
+Before: C++11
+
+---
+
 ```cpp
 template <typename... TArgs>
 ETL_CONSTEXPR14 value_type& emplace(TArgs&&... args) ETL_NOEXCEPT
 ```
 **Description**  
-Returns the error if has_value() returns false.
-Undefined if has_value() returns true.
+Create from arguments.
 Since: C++11
 
 ---
@@ -574,15 +608,411 @@ Const class member access operator.
 ---
 
 ```cpp
-value_type& operator *()
+value_type& operator *() &
 ```
-**Description**  
+**Description**
 Dereference operator.
 
 ---
 
 ```cpp
-const value_type& operator *() const
+const value_type& operator *() const&
 ```
-**Description**  
+**Description**
 Dereference operator.
+
+---
+
+```cpp
+value_type&& operator *() &&
+```
+**Description**
+Dereference operator.
+Since: C++11
+
+---
+
+```cpp
+const value_type&& operator *() const&&
+```
+**Description**
+Dereference operator.
+Since: C++11
+
+---
+
+```cpp
+ETL_NODISCARD
+ETL_CONSTEXPR14
+value_type* begin() ETL_NOEXCEPT
+```
+**Description**
+Returns a pointer to the value if has_value() returns true, otherwise returns nullptr.
+Allows expected to be used as a range of 0 or 1 elements. Not valid for void specialisation.
+
+---
+
+```cpp
+ETL_NODISCARD
+ETL_CONSTEXPR14
+const value_type* begin() const ETL_NOEXCEPT
+```
+**Description**
+Returns a pointer to the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.
+
+---
+
+```cpp
+ETL_NODISCARD
+ETL_CONSTEXPR14
+value_type* end() ETL_NOEXCEPT
+```
+**Description**
+Returns a pointer past the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.
+
+---
+
+```cpp
+ETL_NODISCARD
+ETL_CONSTEXPR14
+const value_type* end() const ETL_NOEXCEPT
+```
+**Description**
+Returns a pointer past the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&>::type>::type>
+auto transform(F&& f) & -> expected<U, TError>
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto transform(F&& f) & -> expected<U, TError>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&>::type>::type>
+auto transform(F&& f) const& -> expected<U, TError>
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto transform(F&& f) const& -> expected<U, TError>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&&>::type>::type>
+auto transform(F&& f) && -> expected<U, TError>
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto transform(F&& f) && -> expected<U, TError>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&&>::type>::type>
+auto transform(F&& f) const&& -> expected<U, TError>
+```
+**Description**
+If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto transform(F&& f) const&& -> expected<U, TError>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&>::type>::type>
+auto and_then(F&& f) & -> U
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>
+auto and_then(F&& f) & -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&>::type>::type>
+auto and_then(F&& f) const& -> U
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto and_then(F&& f) const& -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&&>::type>::type>
+auto and_then(F&& f) && -> U
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto and_then(F&& f) && -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&&>::type>::type>
+auto and_then(F&& f) const&& -> U
+```
+**Description**
+If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
+auto and_then(F&& f) const&& -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error().
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
+auto or_else(F&& f) & -> U
+```
+**Description**
+If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
+auto or_else(F&& f) & -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
+auto or_else(F&& f) const& -> U
+```
+**Description**
+If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
+auto or_else(F&& f) const& -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
+auto or_else(F&& f) && -> U
+```
+**Description**
+If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
+auto or_else(F&& f) && -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
+auto or_else(F&& f) const&& -> U
+```
+**Description**
+If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
+auto or_else(F&& f) const&& -> U
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
+auto transform_error(F&& f) & -> expected<TValue, U>
+```
+**Description**
+If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
+auto transform_error(F&& f) & -> expected<TValue, U>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
+auto transform_error(F&& f) const& -> expected<TValue, U>
+```
+**Description**
+If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
+auto transform_error(F&& f) const& -> expected<TValue, U>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
+auto transform_error(F&& f) && -> expected<TValue, U>
+```
+**Description**
+If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
+auto transform_error(F&& f) && -> expected<TValue, U>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
+auto transform_error(F&& f) const&& -> expected<TValue, U>
+```
+**Description**
+If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below.
+Since: C++11
+
+---
+
+```cpp
+template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
+auto transform_error(F&& f) const&& -> expected<TValue, U>
+```
+**Description**
+For void specialisation.
+If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object.
+Since: C++11
+