docs: add godoc and README files in English and Russian

slice.go

@@ -6,19 +6,33 @@ import (
 	"strings"
 )
 
+// Slice is a generic slice wrapper with convenience methods.
 type Slice[T any] []T
 
+// NewSliceFrom returns a copy of slice as a Slice.
 func NewSliceFrom[T any](slice []T) Slice[T] {
 	s := make(Slice[T], len(slice))
 	copy(s, slice)
 	return s
 }
-func (s Slice[T]) Len() int        { return len(s) }
-func (s Slice[T]) Cap() int        { return cap(s) }
-func (s Slice[T]) Get(index int) T { return s[index] }
-func (s Slice[T]) Last() T         { return s.Get(s.Len() - 1) }
-func (s Slice[T]) First() T        { return s.Get(0) }
 
+// Len returns the number of elements in s.
+func (s Slice[T]) Len() int { return len(s) }
+
+// Cap returns the capacity of s.
+func (s Slice[T]) Cap() int { return cap(s) }
+
+// Get returns the element at index.
+func (s Slice[T]) Get(index int) T { return s[index] }
+
+// Last returns the last element.
+func (s Slice[T]) Last() T { return s.Get(s.Len() - 1) }
+
+// First returns the first element.
+func (s Slice[T]) First() T { return s.Get(0) }
+
+// Index returns the first index of el or -1 when el is not present.
+// Comparison uses reflect.DeepEqual.
 func (s Slice[T]) Index(el T) int {
 	for i := range s {
 		if reflect.DeepEqual(s[i], el) {
@@ -28,7 +42,10 @@ func (s Slice[T]) Index(el T) int {
 	return -1
 }
 
+// Push appends e and returns the resulting slice.
 func (s Slice[T]) Push(e T) Slice[T] { return append(s, e) }
+
+// Pop removes the element at index and returns the resulting slice.
 func (s Slice[T]) Pop(index int) Slice[T] {
 	if index == 0 {
 		return s[1:]
@@ -38,6 +55,8 @@ func (s Slice[T]) Pop(index int) Slice[T] {
 	copy(out[index:], s[index+1:])
 	return out
 }
+
+// Remove removes the first matching element and returns the resulting slice.
 func (s Slice[T]) Remove(el T) Slice[T] {
 	index := s.Index(el)
 	if index == -1 {
@@ -46,12 +65,14 @@ func (s Slice[T]) Remove(el T) Slice[T] {
 	return s.Pop(index)
 }
 
-// Swap is mutable func
+// Swap swaps two elements in place and returns s.
 func (s Slice[T]) Swap(i, j int) Slice[T] {
 	s[i], s[j] = s[j], s[i]
 	return s
 }
 
+// Equal reports whether both slices have the same length and pairwise equal
+// elements according to reflect.DeepEqual.
 func (s Slice[T]) Equal(s2 Slice[T]) bool {
 	if s.Len() != s2.Len() {
 		return false
@@ -64,11 +85,14 @@ func (s Slice[T]) Equal(s2 Slice[T]) bool {
 	return true
 }
 
+// ToArray returns a copy of s as a built-in slice.
 func (s Slice[T]) ToArray() []T {
 	out := make([]T, len(s))
 	copy(out, s)
 	return out
 }
+
+// ToAnyArray returns a copy of s converted to []any.
 func (s Slice[T]) ToAnyArray() []any {
 	out := make([]any, len(s))
 	for i, v := range s {
@@ -76,9 +100,14 @@ func (s Slice[T]) ToAnyArray() []any {
 	}
 	return out
 }
-func (s Slice[T]) ToSet() Set[T]     { return NewSetFrom(s) }
+
+// ToSet returns a Set built from the slice values.
+func (s Slice[T]) ToSet() Set[T] { return NewSetFrom(s) }
+
+// ToTuple returns a Tuple view of s without copying.
 func (s Slice[T]) ToTuple() Tuple[T] { return NewTupleFrom(s) }
 
+// Filter returns a new Slice containing only elements accepted by f.
 func (s Slice[T]) Filter(f func(e T) bool) Slice[T] {
 	out := make(Slice[T], 0)
 	for _, v := range s {
@@ -88,6 +117,8 @@ func (s Slice[T]) Filter(f func(e T) bool) Slice[T] {
 	}
 	return out
 }
+
+// ForEach calls f for every element and returns s.
 func (s Slice[T]) ForEach(f func(int, T)) Slice[T] {
 	for i, v := range s {
 		f(i, v)
@@ -95,7 +126,7 @@ func (s Slice[T]) ForEach(f func(int, T)) Slice[T] {
 	return s
 }
 
-// Map is mutable func
+// Map applies f to each element in place and returns s.
 func (s Slice[T]) Map(f func(e T) T) Slice[T] {
 	for i, v := range s {
 		s[i] = f(v)
@@ -103,6 +134,8 @@ func (s Slice[T]) Map(f func(e T) T) Slice[T] {
 	return s
 }
 
+// Join formats every element with fmt.Sprintf("%v", value) and joins them
+// using sep.
 func (s Slice[T]) Join(sep string) string {
 	st := make([]string, len(s))
 	for i, v := range s {