kstd: add nodiscard to result success and failure

1 files changed, 14 insertions, 3 deletions

diff --git a/libs/kstd/kstd/result.hpp b/libs/kstd/kstd/result.hpp
index 7b027a8d..ae15f079 100644
--- a/libs/kstd/kstd/result.hpp
+++ b/libs/kstd/kstd/result.hpp
@@ -10,22 +10,33 @@
 namespace kstd
 {
 
+  //! A type alias to hold results of functions that may fail.
+  //!
+  //! This is a convenience alias mapping to std::expected. It is intended to reduce the duplication of the unexpected
+  //! type across the codebase.
   template<typename SuccessType>
   using result = std::expected<SuccessType, error_code>;
 
+  //! Create a new success case.
+  //!
+  //! @param value The value to to stash in the success result.
   template<typename SuccessType>
     requires(!std::is_void_v<SuccessType>)
-  constexpr auto inline success(SuccessType && value) -> result<std::remove_cvref_t<SuccessType>>
+  [[nodiscard]] constexpr auto inline success(SuccessType && value) -> result<std::remove_cvref_t<SuccessType>>
   {
     return result<std::remove_cvref_t<SuccessType>>{std::in_place, std::forward<SuccessType>(value)};
   }
 
-  constexpr auto inline success() -> result<void>
+  //! Create an empty success case.
+  [[nodiscard]] constexpr auto inline success() -> result<void>
   {
     return result<void>{std::in_place};
   }
 
-  constexpr auto inline failure(error_code error) -> std::unexpected<error_code>
+  //! Create a failure case.
+  //!
+  //! @param error The error that occurred.
+  [[nodiscard]] constexpr auto inline failure(error_code error) -> std::unexpected<error_code>
   {
     return std::unexpected(error);
   }