Merge pull request #84 from myyrakle/doc/#83

[#83] 문서화 보완

README.md

@@ -1,6 +1,6 @@
 # gost
 
-![](https://img.shields.io/badge/language-Go-00ADD8) ![](https://img.shields.io/badge/version-v0.7.2-brightgreen) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+![](https://img.shields.io/badge/language-Go-00ADD8) ![](https://img.shields.io/badge/version-v0.7.3-brightgreen) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 ![](./etc/gorris.jpg)
 
@@ -11,7 +11,7 @@ Experience the true taste of Rust in Go
 ## Install
 
 ```
-go get github.com/myyrakle/[email protected].2
+go get github.com/myyrakle/[email protected].3
 ```
 
 ## Example

btree_map.go

@@ -12,6 +12,7 @@ type _NodeType int8
 const _LEAF = _NodeType(0)
 const _INTERNAL = _NodeType(1)
 
+// An ordered map based on a B-Tree.
 type BTreeMap[K Ord[K], V any] struct {
 	root *BTreeNode[K, V]
 	len  uint
@@ -37,6 +38,13 @@ func BTreeMapNew[K Ord[K], V any]() BTreeMap[K, V] {
 // Inserts a key-value pair into the map.
 // If the map did not have this key present, None is returned.
 // If the map did have this key present, the value is updated, and the old value is returned. The key is not updated, though; this matters for types that can be == without being identical. See the module-level documentation for more.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	gost.AssertEq(someMap.Insert(gost.String("foo"), gost.I32(1)), None[gost.I32]())
+//	gost.AssertEq(someMap.IsEmpty(), gost.Bool(false)))
+//
+//	someMap.Insert(gost.String("foo"), gost.I32(2))
+//	gost.AssertEq(someMap.Insert(gost.String("foo"), gost.I32(3)), Some[gost.I32](gost.I32(2)))
 func (self *BTreeMap[K, V]) Insert(key K, value V) Option[V] {
 	// If tree is empty
 	if self.root == nil {
@@ -105,6 +113,10 @@ func (self *BTreeMap[K, V]) Insert(key K, value V) Option[V] {
 
 // Returns true if the map contains a value for the specified key.
 // The key may be any borrowed form of the map’s key type, but the ordering on the borrowed form must match the ordering on the key type.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	gost.AssertEq(someMap.ContainsKey(gost.String("foo")), gost.Bool(true))
 func (self *BTreeMap[K, V]) ContainsKey(key K) Bool {
 	if self.root == nil {
 		return false
@@ -115,22 +127,39 @@ func (self *BTreeMap[K, V]) ContainsKey(key K) Bool {
 }
 
 // Returns the number of elements in the map.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	gost.AssertEq(someMap.Len(), gost.USize(1))
 func (self *BTreeMap[K, V]) Len() USize {
 	return USize(self.len)
 }
 
 // Returns true if the map contains no elements.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	gost.AssertEq(someMap.IsEmpty(), gost.Bool(false))
 func (self *BTreeMap[K, V]) IsEmpty() Bool {
 	return self.len == 0
 }
 
 // Clears the map, removing all elements.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	someMap.Clear()
+//	gost.AssertEq(someMap.IsEmpty(), gost.Bool(true))
 func (self *BTreeMap[K, V]) Clear() {
 	self.root = nil
 	self.len = 0
 }
 
 // Returns value corresponding to the key.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	gost.AssertEq(someMap.Get(gost.String("foo")), Some[gost.I32](gost.I32(1)))
 func (self *BTreeMap[K, V]) Get(key K) Option[V] {
 	if self.root == nil {
 		return None[V]()
@@ -146,6 +175,10 @@ func (self *BTreeMap[K, V]) Get(key K) Option[V] {
 
 // Removes a key from the map, returning the value at the key if the key was previously in the map.
 // The key may be any borrowed form of the map’s key type, but the ordering on the borrowed form must match the ordering on the key type.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	gost.AssertEq(someMap.Remove(gost.String("foo")), Some[gost.I32](gost.I32(1)))
 func (self *BTreeMap[K, V]) Remove(key K) Option[V] {
 	if self.root == nil {
 		return None[V]()
@@ -808,6 +841,7 @@ func (self BTreeMapIter[K, V]) Rev() Iterator[Pair[K, V]] {
 	}
 }
 
+// Collect to Vec
 func (self BTreeMapIter[K, V]) CollectToVec() Vec[Pair[K, V]] {
 	return self.vec
 }
@@ -826,12 +860,20 @@ func (self BTreeMapIter[K, V]) CollectToLinkedList() LinkedList[Pair[K, V]] {
 	}
 }
 
+// An iterator visiting all keys in arbitrary order. The iterator element type is K.
 type BTreeMapKeys[K any] struct {
 	vec      Vec[K]
 	position USize
 }
 
 // An iterator visiting all keys in arbitrary order. The iterator element type is K.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	someMap.Insert(gost.String("bar"), gost.I32(2))
+//	someMap.Insert(gost.String("baz"), gost.I32(3))
+//	keys := someMap.Keys().CollectToVec()
+//	gost.AssertEq(keys.Len(), gost.USize(3))
 func (self BTreeMap[K, V]) Keys() Iterator[K] {
 	vec := Vec[K]{}
 
@@ -932,12 +974,20 @@ func (self BTreeMapKeys[K]) CollectToLinkedList() LinkedList[K] {
 	}
 }
 
+// An iterator visiting all values in arbitrary order. The iterator element type is V.
 type BTreeMapValues[V any] struct {
 	vec      Vec[V]
 	position USize
 }
 
 // An iterator visiting all values in arbitrary order. The iterator element type is V.
+//
+//	someMap := gost.BTreeMapNew[gost.String, gost.I32]()
+//	someMap.Insert(gost.String("foo"), gost.I32(1))
+//	someMap.Insert(gost.String("bar"), gost.I32(2))
+//	someMap.Insert(gost.String("baz"), gost.I32(3))
+//	values := someMap.Values().CollectToVec()
+//	gost.AssertEq(values.Len(), gost.USize(3))
 func (self BTreeMap[K, V]) Values() Iterator[V] {
 	vec := Vec[V]{}
 

btree_set.go

@@ -5,6 +5,7 @@ import (
 	"strings"
 )
 
+// A ordered set based on a B-Tree.
 type BTreeSet[K Ord[K]] struct {
 	_treemap BTreeMap[K, struct{}]
 }
@@ -15,12 +16,24 @@ func BTreeSetNew[K Ord[K]]() BTreeSet[K] {
 }
 
 // Clears the set, removing all elements.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	set.Insert(gost.I32(1))
+//	set.Insert(gost.I32(2))
+//	set.Clear()
+//	gost.AssertEq(set.Len(), gost.USize(0))
 func (self *BTreeSet[K]) Clear() {
 	self._treemap.Clear()
 }
 
 // Returns true if the set contains an element equal to the value.
 // The value may be any borrowed form of the set’s element type, but the ordering on the borrowed form must match the ordering on the element type.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	set.Insert(gost.I32(1))
+//	set.Insert(gost.I32(2))
+//	gost.Assert(set.Contains(gost.I32(1)))
+//	gost.Assert(!set.Contains(gost.I32(3)))
 func (self *BTreeSet[K]) Contains(key K) Bool {
 	return self._treemap.ContainsKey(key)
 }
@@ -29,6 +42,10 @@ func (self *BTreeSet[K]) Contains(key K) Bool {
 // Returns whether the value was newly inserted. That is:
 // If the set did not previously contain an equal value, true is returned.
 // If the set already contained an equal value, false is returned, and the entry is not updated.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	gost.Assert(set.Insert(gost.I32(1)))
+//	gost.Assert(!set.Insert(gost.I32(1)))
 func (self *BTreeSet[K]) Insert(key K) Bool {
 	result := self._treemap.Insert(key, struct{}{})
 
@@ -41,6 +58,12 @@ func (self *BTreeSet[K]) Insert(key K) Bool {
 
 // If the set contains an element equal to the value, removes it from the set and drops it. Returns whether such an element was present.
 // The value may be any borrowed form of the set’s element type, but the ordering on the borrowed form must match the ordering on the element type.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	set.Insert(gost.I32(1))
+//	set.Insert(gost.I32(2))
+//	gost.Assert(set.Remove(gost.I32(1)))
+//	gost.Assert(!set.Remove(gost.I32(3)))
 func (self *BTreeSet[K]) Remove(key K) Bool {
 	result := self._treemap.Remove(key)
 
@@ -52,15 +75,28 @@ func (self *BTreeSet[K]) Remove(key K) Bool {
 }
 
 // Returns true if the set contains no elements.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	gost.Assert(set.IsEmpty())
+//
+//	set.Insert(gost.I32(1))
+//	gost.Assert(!set.IsEmpty())
 func (self *BTreeSet[K]) IsEmpty() Bool {
 	return self._treemap.IsEmpty()
 }
 
 // Returns the number of elements in the set.
+//
+//	set := gost.BTreeSetNew[Int]()
+//	gost.AssertEq(set.Len(), gost.USize(0))
+//
+//	set.Insert(gost.I32(1))
+//	gost.AssertEq(set.Len(), gost.USize(1))
 func (self *BTreeSet[K]) Len() USize {
 	return self._treemap.Len()
 }
 
+// Returns an iterator over the set.
 type BTreeSetIter[K Ord[K]] struct {
 	vec      Vec[K]
 	position USize

clone.go

@@ -2,6 +2,7 @@ package gost
 
 import "reflect"
 
+// A common trait for the ability to explicitly duplicate an object.
 type Clone[T any] interface {
 	Clone() T
 }

cmp.go

@@ -9,6 +9,7 @@ const OrderingLess Ordering = Ordering(-1)
 const OrderingEqual Ordering = Ordering(0)
 const OrderingGreater Ordering = Ordering(1)
 
+// Trait for types that form a total order.
 type Ord[T any] interface {
 	Cmp(rhs T) Ordering
 	Eq[T]
@@ -184,6 +185,7 @@ func castToOrd[T any](value T) Option[Ord[T]] {
 	}
 }
 
+// Trait for equality comparisons which are equivalence relations.
 type Eq[T any] interface {
 	Eq(rhs T) Bool
 }

convert.go

@@ -1,5 +1,6 @@
 package gost
 
+// Used to do a cheap reference-to-reference conversion.
 type AsRef[T any] interface {
 	AsRef() *T
 }

fmt.go

@@ -5,6 +5,7 @@ import (
 	"reflect"
 )
 
+// Format trait for an empty format, {}
 type Display[T any] interface {
 	Display() String
 }
@@ -91,6 +92,8 @@ func castToDisplay[T any](value T) Option[Display[T]] {
 	}
 }
 
+// ? formatting.
+// Debug should format the output in a programmer-facing, debugging context.
 type Debug[T any] interface {
 	Debug() string
 }