- update all documentation to be in godoc style

README.md

@@ -572,12 +572,12 @@ Some data structures (e.g. TreeMap, TreeSet) require a comparator function to au
 
 Comparator is defined as:
 
-Return values:
+Return values (int):
 
 ```go
--1, if a < b
- 0, if a == b
- 1, if a > b
+negative , if a < b
+zero     , if a == b
+positive , if a > b
 ```
 
 Comparator signature:

containers/containers.go

@@ -24,11 +24,18 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+// Package containers provides core interfaces and functions data structures.
+//
+// Container is the base interface for all data structures to implement.
+//
+// Iterators provide stateful iterators.
+//
+// Enumerable provides Ruby inspired (each, select, map, find, any?, etc.) container functions.
 package containers
 
 import "github.com/emirpasic/gods/utils"
 
-// Container is base interface that all data structures implement
+// Container is base interface that all data structures implement.
 type Container interface {
 	Empty() bool
 	Size() int

containers/enumerable.go

@@ -24,9 +24,6 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Enumerable functions for ordered containers.
-// Ruby's enumerable inspired package.
-
 package containers
 
 // EnumerableWithIndex provides functions for ordered containers whose values can be fetched by an index.

containers/iterator.go

@@ -24,8 +24,6 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Stateful iterator pattern for ordered containers.
-
 package containers
 
 // IteratorWithIndex is stateful iterator for ordered containers whose values can be fetched by an index.

lists/arraylist/arraylist.go

@@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of list using a slice.
+// Package arraylist implements the array list.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/List_%28abstract_data_type%29
-
+//
+// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29
 package arraylist
 
 import (

lists/doublylinkedlist/doublylinkedlist.go

@@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of doubly linked list.
+// Package doublylinkedlist implements the doubly-linked list.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Doubly_linked_list
-
+//
+// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29
 package doublylinkedlist
 
 import (

lists/lists.go

@@ -16,6 +16,11 @@ License along with this library. See the file LICENSE included
 with this distribution for more information.
 */
 
+// Package lists provides abstract List interface for that all concrete lists should implement.
+//
+// In computer science, a list or sequence is an abstract data type that represents an ordered sequence of values, where the same value may occur more than once. An instance of a list is a computer representation of the mathematical concept of a finite sequence; the (potentially) infinite analog of a list is a stream.  Lists are a basic example of containers, as they contain other values. If the same value occurs multiple times, each occurrence is considered a distinct item.
+//
+// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29
 package lists
 
 import (

lists/singlylinkedlist/singlylinkedlist.go

@@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of doubly linked list.
+// Package singlylinkedlist implements the singly-linked list.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Linked_list#Singly_linked_list
-
+//
+// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29
 package singlylinkedlist
 
 import (

maps/hashmap/hashmap.go

@@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of unorder map backed by a hash table.
+// Package hashmap implements a map backed by a hash table.
+//
 // Elements are unordered in the map.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Associative_array
-
+//
+// Reference: http://en.wikipedia.org/wiki/Associative_array
 package hashmap
 
 import (

maps/maps.go

@@ -24,6 +24,17 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+// Package maps provides abstract Map interface for that all concrete maps should implement.
+//
+// In computer science, an associative array, map, symbol table, or dictionary is an abstract data type composed of a collection of (key, value) pairs, such that each possible key appears just once in the collection.
+//
+// Operations associated with this data type allow:
+// - the addition of a pair to the collection
+// - the removal of a pair from the collection
+// - the modification of an existing pair
+// - the lookup of a value associated with a particular key
+//
+// Reference: https://en.wikipedia.org/wiki/Associative_array
 package maps
 
 import "github.com/emirpasic/gods/containers"

maps/treemap/treemap.go

@@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of order map backed by red-black tree.
+// Package treemap implements a map backed by red-black tree.
+//
 // Elements are ordered by key in the map.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Associative_array
-
+//
+// Reference: http://en.wikipedia.org/wiki/Associative_array
 package treemap
 
 import (

sets/hashset/hashset.go

@@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of set backed by a hash table.
+// Package hashset implements a set backed by a hash table.
+//
 // Structure is not thread safe.
+//
 // References: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29
-
 package hashset
 
 import (

sets/sets.go

@@ -16,6 +16,11 @@ License along with this library. See the file LICENSE included
 with this distribution for more information.
 */
 
+// Package sets provides abstract Set interface for that all concrete sets should implement.
+//
+// In computer science, a set is an abstract data type that can store certain values and no repeated values. It is a computer implementation of the mathematical concept of a finite set. Unlike most other collection types, rather than retrieving a specific element from a set, one typically tests a value for membership in a set.
+//
+// Reference: https://en.wikipedia.org/wiki/Set_%28abstract_data_type%29
 package sets
 
 import "github.com/emirpasic/gods/containers"

sets/treeset/treeset.go

@@ -16,10 +16,11 @@ License along with this library. See the file LICENSE included
 with this distribution for more information.
 */
 
-// Implementation of an ordered set backed by a red-black tree.
+// Package treeset implements a tree backed by a red-black tree.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29
-
+//
+// Reference: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29
 package treeset
 
 import (

stacks/arraystack/arraystack.go

@@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of stack backed by ArrayList.
+// Package arraystack implements a stack backed by array list.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29
-
+//
+// Reference: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29#Array
 package arraystack
 
 import (

stacks/linkedliststack/linkedliststack.go

@@ -24,11 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of stack backed by our singly linked list.
-// Used by red-black tree during in-order traversal.
+// Package linkedliststack implements a stack backed by a singly-linked list.
+//
 // Structure is not thread safe.
-// References: http://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29
-
+//
+// Reference:https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29#Linked_list
 package linkedliststack
 
 import (

stacks/stacks.go

@@ -24,6 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+// Package stacks provides abstract Stack interface for that all concrete stacks should implement.
+//
+// In computer science, a stack is an abstract data type that serves as a collection of elements, with two principal operations: push, which adds an element to the collection, and pop, which removes the most recently added element that was not yet removed. The order in which elements come off a stack gives rise to its alternative name, LIFO (for last in, first out). Additionally, a peek operation may give access to the top without modifying the stack.
+//
+// Reference: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29
 package stacks
 
 import "github.com/emirpasic/gods/containers"

trees/binaryheap/binaryheap.go

@@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of binary heap backed by ArrayList.
+// Package binaryheap implements a binary heap backed by array list.
+//
 // Comparator defines this heap as either min or max heap.
+//
 // Structure is not thread safe.
+//
 // References: http://en.wikipedia.org/wiki/Binary_heap
-
 package binaryheap
 
 import (

trees/redblacktree/redblacktree.go

@@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Implementation of Red-black tree.
+// Package redblacktree implements a red-black tree.
+//
 // Used by TreeSet and TreeMap.
+//
 // Structure is not thread safe.
+//
 // References: http://en.wikipedia.org/wiki/Red%E2%80%93black_tree
-
 package redblacktree
 
 import (

trees/trees.go

@@ -24,6 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+// Package trees provides abstract Tree interface for that all concrete trees should implement.
+//
+// In computer science, a tree is a widely used abstract data type (ADT) or data structure implementing this ADT that simulates a hierarchical tree structure, with a root value and subtrees of children with a parent node, represented as a set of linked nodes.
+//
+// Reference: https://en.wikipedia.org/wiki/Tree_%28data_structure%29
 package trees
 
 import "github.com/emirpasic/gods/containers"

utils/comparator.go

@@ -29,10 +29,10 @@ package utils
 // Comparator will make type assertion (see IntComparator for example),
 // which will panic if a or b are not of the asserted type.
 //
-// Should return:
-//   -1, if a < b
-//    0, if a == b
-//    1, if a > b
+// Should return a number:
+//    negative , if a < b
+//    zero     , if a == b
+//    positive , if a > b
 type Comparator func(a, b interface{}) int
 
 // IntComparator provides a basic comparison on ints

utils/sort.go

@@ -24,14 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-// Util methods for sorting a slice of values with respect to the comparator
-
 package utils
 
 import "sort"
 
-// Sort sorts values (in-place)
-// Uses Go's sort (hybrid of quicksort for large and then insertion sort for smaller slices)
+// Sort sorts values (in-place) with respect to the given comparator.
+//
+// Uses Go's sort (hybrid of quicksort for large and then insertion sort for smaller slices).
 func Sort(values []interface{}, comparator Comparator) {
 	sort.Sort(sortable{values, comparator})
 }