Improve documentation for option and result packages

Author: BooleanCat

iter/ops/unary.go

@@ -5,12 +5,12 @@ import (
 	"github.com/BooleanCat/go-functional/result"
 )
 
-// UnwrapOption calls unwrap on an [option.Option].
+// UnwrapOption calls Unwrap on an [option.Option].
 func UnwrapOption[T any](o option.Option[T]) T {
 	return o.Unwrap()
 }
 
-// UnwrapResult calls unwrap on a [result.Result].
+// UnwrapResult calls Unwrap on a [result.Result].
 func UnwrapResult[T any](r result.Result[T]) T {
 	return r.Unwrap()
 }

option/json.go

@@ -2,6 +2,10 @@ package option
 
 import "encoding/json"
 
+// MarshalJSON implements the [json.Marshaler] interface.
+//
+//   - [Some] variants will be marshaled as their underlying value.
+//   - [None] variants will be marshaled as "null".
 func (o Option[T]) MarshalJSON() ([]byte, error) {
 	if value, ok := o.Value(); ok {
 		return json.Marshal(value)
@@ -10,8 +14,10 @@ func (o Option[T]) MarshalJSON() ([]byte, error) {
 	return []byte("null"), nil
 }
 
-var _ json.Marshaler = Option[struct{}]{}
-
+// UnmarshalJSON implements the [json.Unmarshaler] interface.
+//
+//   - Values will be marshed as [Some] variants.
+//   - "null"s will be marshaled as [None] variants.
 func (o *Option[T]) UnmarshalJSON(data []byte) error {
 	*o = None[T]()
 
@@ -26,4 +32,7 @@ func (o *Option[T]) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
-var _ json.Unmarshaler = &Option[struct{}]{}
+var (
+	_ json.Unmarshaler = &Option[struct{}]{}
+	_ json.Marshaler   = Option[struct{}]{}
+)

option/option.go

@@ -2,23 +2,24 @@ package option
 
 import "fmt"
 
-// Option represents an optional value. The Some variant contains a value and
-// the None variant represents the absence of a value.
+// Option represents an optional value. The [Some] variant contains a value and
+// the [None] variant represents the absence of a value.
 type Option[T any] struct {
 	value   T
 	present bool
 }
 
-// Some instantiates an Option with a value.
+// Some instantiates an [Option] with a value.
 func Some[T any](value T) Option[T] {
 	return Option[T]{value, true}
 }
 
-// None instantiates an Option with no value.
+// None instantiates an [Option] with no value.
 func None[T any]() Option[T] {
 	return Option[T]{}
 }
 
+// String implements the [fmt.Stringer] interface.
 func (o Option[T]) String() string {
 	if o.present {
 		return fmt.Sprintf("Some(%v)", o.value)
@@ -29,8 +30,8 @@ func (o Option[T]) String() string {
 
 var _ fmt.Stringer = Option[struct{}]{}
 
-// Unwrap returns the underlying value of a Some variant, or panics if called
-// on a None variant.
+// Unwrap returns the underlying value of a [Some] variant, or panics if called
+// on a [None] variant.
 func (o Option[T]) Unwrap() T {
 	if o.present {
 		return o.value
@@ -39,8 +40,8 @@ func (o Option[T]) Unwrap() T {
 	panic("called `Option.Unwrap()` on a `None` value")
 }
 
-// UnwrapOr returns the underlying value of a Some variant, or the provided
-// value on a None variant.
+// UnwrapOr returns the underlying value of a [Some] variant, or the provided
+// value on a [None] variant.
 func (o Option[T]) UnwrapOr(value T) T {
 	if o.present {
 		return o.value
@@ -49,8 +50,8 @@ func (o Option[T]) UnwrapOr(value T) T {
 	return value
 }
 
-// UnwrapOrElse returns the underlying value of a Some variant, or the result
-// of calling the provided function on a None variant.
+// UnwrapOrElse returns the underlying value of a [Some] variant, or the result
+// of calling the provided function on a [None] variant.
 func (o Option[T]) UnwrapOrElse(f func() T) T {
 	if o.present {
 		return o.value
@@ -59,8 +60,8 @@ func (o Option[T]) UnwrapOrElse(f func() T) T {
 	return f()
 }
 
-// UnwrapOrZero returns the underlying value of a Some variant, or the zero
-// value on a None variant.
+// UnwrapOrZero returns the underlying value of a [Some] variant, or the zero
+// value on a [None] variant.
 func (o Option[T]) UnwrapOrZero() T {
 	if o.present {
 		return o.value
@@ -70,18 +71,18 @@ func (o Option[T]) UnwrapOrZero() T {
 	return value
 }
 
-// IsSome returns true if the Option contains a value.
+// IsSome returns true if the [Option] is a [Some] variant.
 func (o Option[T]) IsSome() bool {
 	return o.present
 }
 
-// IsNone returns true if the Option does not contain a value.
+// IsNone returns true if the [Option] is a [None] varaint.
 func (o Option[T]) IsNone() bool {
 	return !o.present
 }
 
-// Value returns the underlying value and true for a Some variant, or the zero
-// value and false for a None variant.
+// Value returns the underlying value and true for a [Some] variant, or the
+// zero value and false for a [None] variant.
 func (o Option[T]) Value() (T, bool) {
 	return o.value, o.present
 }

result/result.go

@@ -2,23 +2,25 @@ package result
 
 import "fmt"
 
-// Result represents failure or success. The Ok variant represents success and
-// contains a value. The Err variant represent a failure and contains an error.
+// Result represents failure or success. The [Ok] variant represents success
+// and contains a value. The [Err] variant represent a failure and contains an
+// error.
 type Result[T any] struct {
 	value T
 	err   error
 }
 
-// Ok instanriates a successful result with a value.
+// Ok instantiates a [Result] with a value.
 func Ok[T any](value T) Result[T] {
 	return Result[T]{value, nil}
 }
 
-// Err instanitates a failed result with an error.
+// Err instantiates a [Result] with an error.
 func Err[T any](err error) Result[T] {
 	return Result[T]{err: err}
 }
 
+// String implements the [fmt.Stringer] interface.
 func (r Result[T]) String() string {
 	if r.err == nil {
 		return fmt.Sprintf("Ok(%v)", r.value)
@@ -27,8 +29,10 @@ func (r Result[T]) String() string {
 	return fmt.Sprintf("Err(%s)", r.err.Error())
 }
 
-// Unwrap returns the underlying value of an Ok variant, or panics if called
-// on an Err variant.
+var _ fmt.Stringer = Result[struct{}]{}
+
+// Unwrap returns the underlying value of an [Ok] variant, or panics if called
+// on an [Err] variant.
 func (r Result[T]) Unwrap() T {
 	if r.err == nil {
 		return r.value
@@ -37,8 +41,8 @@ func (r Result[T]) Unwrap() T {
 	panic("called `Result.Unwrap()` on an `Err` value")
 }
 
-// UnwrapOr returns the underlying value of an Ok variant, or the provided
-// value on an Err variant.
+// UnwrapOr returns the underlying value of an [Ok] variant, or the provided
+// value on an [Err] variant.
 func (r Result[T]) UnwrapOr(value T) T {
 	if r.err == nil {
 		return r.value
@@ -47,8 +51,8 @@ func (r Result[T]) UnwrapOr(value T) T {
 	return value
 }
 
-// UnwrapOrElse returns the underlying value of an Ok variant, or the result
-// of calling the provided function on an Err variant.
+// UnwrapOrElse returns the underlying value of an [Ok] variant, or the result
+// of calling the provided function on an [Err] variant.
 func (r Result[T]) UnwrapOrElse(f func() T) T {
 	if r.err == nil {
 		return r.value
@@ -57,8 +61,8 @@ func (r Result[T]) UnwrapOrElse(f func() T) T {
 	return f()
 }
 
-// UnwrapOrZero returns the underlying value of an Ok variant, or the zero
-// value of an Err variant.
+// UnwrapOrZero returns the underlying value of an [Ok] variant, or the zero
+// value of an [Err] variant.
 func (r Result[T]) UnwrapOrZero() T {
 	if r.err == nil {
 		return r.value
@@ -68,24 +72,24 @@ func (r Result[T]) UnwrapOrZero() T {
 	return value
 }
 
-// IsOk returns true if the Result is an Ok variant.
+// IsOk returns true if the [Result] is an [Ok] variant.
 func (r Result[T]) IsOk() bool {
 	return r.err == nil
 }
 
-// IsErr returns true if the Result is an Err variant.
+// IsErr returns true if the [Result] is an [Err] variant.
 func (r Result[T]) IsErr() bool {
 	return r.err != nil
 }
 
-// Value returns the underlying value and nil for an Ok variant, or the zero
-// value and an error for an Error variant.
+// Value returns the underlying value and nil for an [Ok] variant, or the zero
+// value and an error for an [Err] variant.
 func (r Result[T]) Value() (T, error) {
 	return r.value, r.err
 }
 
-// Unwrap returns the underlying error of an Err variant, or panics if called
-// on an Ok variant.
+// UnwrapErr returns the underlying error of an [Err] variant, or panics if called
+// on an [Ok] variant.
 func (r Result[T]) UnwrapErr() error {
 	if r.IsOk() {
 		panic("called `Result.UnwrapErr()` on an `Ok` value")