From 317b0cde87546bcd875ef347ef9a479712286284 Mon Sep 17 00:00:00 2001
From: Erica Marigold <hi@devcomp.xyz>
Date: Fri, 26 Apr 2024 22:16:37 +0530
Subject: [PATCH] docs: include comments for conversion module & fix options
 intro hrefs

* Included moonwave doc comments for `Option` <-> `Result` conversion module
* Fixed incorrect href format in `Option` module introduction
---
 lib/conversion.luau | 117 +++++++++++++++++++++++++++++++++++++++++++-
 lib/option.luau     |   5 +-
 2 files changed, 118 insertions(+), 4 deletions(-)

diff --git a/lib/conversion.luau b/lib/conversion.luau
index e77e38e..a55588b 100644
--- a/lib/conversion.luau
+++ b/lib/conversion.luau
@@ -19,6 +19,24 @@ export type Result<T, E> = result.Result<T, E>
 local Ok = result.Ok
 local Err = result.Err
 
+--[=[
+	@within Result
+
+	Converts from [Result]`<T, E>` to [Option]`<T>`.
+
+	Converts `self` into an [Option]`<T>`, and discarding the error, if any.
+
+	```lua
+	local x: Result<number, string> = Ok(2)
+	assert(x:ok() == Some(2))
+
+	x = Err("Nothing here")
+	assert(x:ok() == None())
+	```
+
+	@param self Result<T, E>
+	@return Option<T>
+]=]
 function Result.ok<T, E>(self: Result<T, E>): Option<T>
 	if self:isOk() then
 		if self._value == nil then
@@ -31,6 +49,24 @@ function Result.ok<T, E>(self: Result<T, E>): Option<T>
 	return None()
 end
 
+--[=[
+	@within Result
+
+	Converts from [Result]`<T, E>` to [Option]`<E>`.
+
+	Converts `self` into an [Option]`<E>`, and discarding the success value, if any.
+
+	```lua
+	local x: Result<number, string> = Ok(2)
+	assert(x:ok() == Some(2))
+
+	x = Err("Nothing here")
+	assert(x:ok() == None())
+	```
+
+	@param self Result<T, E>
+	@return Option<E>
+]=]
 function Result.err<T, E>(self: Result<T, E>): Option<E>
 	if self:isErr() then
 		return Option.new(self._error) :: Option<E>
@@ -39,9 +75,27 @@ function Result.err<T, E>(self: Result<T, E>): Option<E>
 	return None()
 end
 
+--[=[
+	@within Result
+
+	Transposes a [Result] of an [Option] into an [Option] of a [Result].
+
+	[Result:Ok]\([Option:None]\) will be mapped to [Option:None]. 
+	[Result:Ok]\([Option:Some]`(_)`\) and [Result:Err]\(`_`\) will be mapped to 
+	[Option:Some]\([Result:Ok]`(_)`\) and [Option:Some]\([Option:Err]`(_)`\).
+
+	```lua
+	type SomeErr = {}
+	
+	local x: Result<Option<number>, SomeErr> = Ok(Some(2))
+	local y: Option<Result<number, SomeErr>> = Some(Ok(2))
+	assert(x:transpose() == y)
+	```
+
+	@param self Result<Option<T>, E>
+	@return Option<Result<T, E>>
+]=]
 function Result.transpose<T, E>(self: Result<Option<T>, E>): Option<Result<T, E>>
-	-- TODO: Instead of checking whether values are nil, use
-	-- utility methods for Options once available
 	if self._value == None() then
 		return None()
 	elseif self:isOkAnd(function(val): boolean
@@ -55,6 +109,27 @@ function Result.transpose<T, E>(self: Result<Option<T>, E>): Option<Result<T, E>
 	error("`Result` is not transposable")
 end
 
+--[=[
+	@within Option
+
+	Transforms the [Option]`<T>` into a [Result]`<T, E>`, mapping [Option:Some]`(v)` 
+	to [Result:Ok]`(v)` and [Option:None] to [Result:Err]`(err)`.
+
+	Arguments passed to [Option:okOr] are eagerly evaluated; if you are passing the result 
+	of a function call, it is recommended to use [Option:okOrElse], which is lazily evaluated.
+
+	```lua
+	local x: Option<string> = Some("foo")
+	assert(x:okOr(0) == Ok("foo"))
+
+	x = None()
+	assert(x:okOr(0) == Err(0))
+	```
+
+	@param self Option<T>
+	@param err E
+	@return Result<T, E>
+]=]
 function Option.okOr<T, E>(self: Option<T>, err: E): Result<T, E>
 	if self:isSome() then
 		return Ok(self._optValue)
@@ -63,6 +138,24 @@ function Option.okOr<T, E>(self: Option<T>, err: E): Result<T, E>
 	return Err(err)
 end
 
+--[=[
+	@within Option
+
+	Transforms the [Option]`<T>` into a [Result]`<T, E>`, mapping [Option:Some]`(v)` to
+	[Result:Ok]`(v)` and [Option:None] to [Result:Err]`(err())`.
+
+	```lua
+	local x: Option<string> = Some("foo")
+	assert(x:okOrElse(function() return 0 end) == Ok("foo"))
+
+	x = None()
+	assert(x:okOrElse(function() return 0 end) == Err(0))
+	```
+
+	@param self Option<T>
+	@param err () -> E
+	@return Result<T, E>
+]=]
 function Option.okOrElse<T, E>(self: Option<T>, err: () -> E): Result<T, E>
 	if self:isSome() then
 		return Ok(self._optValue :: T)
@@ -71,6 +164,26 @@ function Option.okOrElse<T, E>(self: Option<T>, err: () -> E): Result<T, E>
 	return Err(err())
 end
 
+--[=[
+	@within Option
+
+	Transposes a [Option] of an [Result] into an [Result] of a [Option].
+
+	[Option:None] will be mapped to [Result:Ok]\([Option:None]\). 
+	[Option:Some]\([Result:Ok]`(_)`\) and [Option:Some]\([Result:Err]\(`_`\)\) will 
+	be mapped to [Result:Ok]\([Option:Some]`(_)`\) and [Result:Err]`(_)`.
+
+	```lua
+	type SomeErr = {}
+	
+	local x: Result<Option<number>, SomeErr> = Ok(Some(5))
+	local y: Option<Result<number, SomeErr>> = Some(Ok(5))
+	assert(x == y:transpose())
+	```
+
+	@param self Option<Result<T, E>>
+	@return Result<Option<T>, E>
+]=]
 function Option.transpose<T, E>(self: Option<Result<T, E>>): Result<Option<T>, E>
 	if self:isSome() then
 		local inner = self._optValue
diff --git a/lib/option.luau b/lib/option.luau
index fa4f422..4a20824 100644
--- a/lib/option.luau
+++ b/lib/option.luau
@@ -3,8 +3,9 @@ local tableEq = require("util").tableEq
 --[=[
 	@class Option
 
-	Type [Option] represents an optional value: every [Option] is either [Some] and contains a 
-	value, or [None], and does not. Common uses of an [Option] may involve:
+	Type [Option] represents an optional value: every [Option] is either [Option:Some] 
+	and contains a value, or [Option:None], and does not. Common uses of an [Option]
+	may involve:
 
 	* Initial values
 	* Return values for functions that are not defined over their entire input range (partial functions)