more package docs

pkg/s3/s3.go

@@ -2,5 +2,7 @@
 Package s3 provides a simple client to interact with a AWS S3 bucket, including the ability to upload, download, and delete objects.
 
 It is based on the official aws-sdk-go-v2 library.
+
+Ref.: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3
 */
 package s3

pkg/sliceutil/sliceutil.go

@@ -1,6 +1,5 @@
 /*
-Package sliceutil provides a collection of slice utility functions,
-including statistics for numerical slices.
+Package sliceutil provides a collection of slice utility functions, including descriptive statistics functions for numerical slices.
 */
 package sliceutil
 

pkg/sqlconn/sqlconn.go

@@ -1,4 +1,7 @@
-// Package sqlconn provides a simple way to manage a SQL-based database connection.
+/*
+Package sqlconn provides a simple way to connect to a SQL database and manage the connection.
+It also provides a way to perform a health check on the connection.
+*/
 package sqlconn
 
 import (

pkg/sqltransaction/sqltransaction.go

@@ -1,4 +1,9 @@
-// Package sqltransaction helps executing a function inside an SQL transaction.
+/*
+Package sqltransaction provides a simple way to execute a function inside an SQL transaction.
+The function to be executed is passed as an argument to the Exec function.
+
+See also the sqlxtransaction package for the same functionality but using the jmoiron/sqlx package.
+*/
 package sqltransaction
 
 import (

pkg/sqlxtransaction/sqlxtransaction.go

@@ -1,4 +1,9 @@
-// Package sqlxtransaction helps executing a function inside an SQLX transaction.
+/*
+Package sqlxtransaction provides a simple way to execute a function inside an SQLX transaction.
+The function to be executed is passed as an argument to the Exec function.
+
+See also the sqltransaction package for the same functionality but using the standard library sql package.
+*/
 package sqlxtransaction
 
 import (

pkg/sqs/sqs.go

@@ -1,2 +1,8 @@
-// Package sqs provides a basic client for AWS SQS (Amazon Simple Queue Service).
+/*
+Package sqs provides a simple client to interact with a AWS SQS (Amazon Simple Queue Service), including the ability to send, receive, and delete messages.
+
+It is based on the official aws-sdk-go-v2 library.
+
+Ref.: https://docs.aws.amazon.com/sdk-for-go/api/service/sqs/
+*/
 package sqs

pkg/stringkey/stringkey.go

@@ -1,6 +1,14 @@
-// Package stringkey creates a key from multiple strings.
-// This package is intended to be used with few small strings.
-// The total number of input bytes should be reasonably small to be compatible with a 64 bit hash.
+/*
+Package stringkey provides the ability to create a simple unique key from multiple strings.
+
+This package uses the farmhash64 algorithm to create a 64 bit hash from the concatenation of input strings.
+The input strings are tab-concatenated, unicode-normalized, converted to lowercase and stripped of multiple, leading and trailing spaces.
+
+This package only works with few small strings and it is not intended to be used for cryptographic purposes.
+The total number of input bytes should be reasonably small to be compatible with a 64 bit hash.
+
+According to the birthday problem, with a 64 bit hash, the hash space is 1.8x10^19 and the probability of a collision is 1% with 6.1×10^8 keys and 50% with 5.1×10^9 keys.
+*/
 package stringkey
 
 import (

pkg/testutil/testutil.go

@@ -1,2 +1,6 @@
-// Package testutil provides common testing utility functions.
+/*
+Package testutil provides common testing utility functions.
+
+The provided functions are intended to simplify the process of setting up tests and to provide a consistent way to do so across the codebase.
+*/
 package testutil

pkg/threadsafe/threadsafe.go

@@ -1,5 +1,8 @@
-// Package threadsafe provides a collection of thread-safe functions that can be safely used between multiple goroutines.
-// Check the sub-packages for specific implementations.
+/*
+Package threadsafe provides an interface for thread-safe functions that can be safely used between multiple goroutines.
+
+See the tsmap and tsslice packages for examples of how to use this interface.
+*/
 package threadsafe
 
 import (

pkg/threadsafe/tsmap/tsmap.go

@@ -1,4 +1,8 @@
-// Package tsmap provides a collection of thread-safe map functions that can be safely used between multiple goroutines.
+/*
+Package tsmap provides a collection of generic thread-safe map utility functions that can be safely used between multiple goroutines.
+
+The provided functions are intended to simplify the process of working with maps in a thread-safe manner.
+*/
 package tsmap
 
 import (

pkg/threadsafe/tsslice/tsslice.go

@@ -1,4 +1,8 @@
-// Package tsslice provides a collection of thread-safe slice functions that can be safely used between multiple goroutines.
+/*
+Package tsslice provides a collection of generic thread-safe slice utility functions that can be safely used between multiple goroutines.
+
+The provided functions are intended to simplify the process of working with slices in a thread-safe manner.
+*/
 package tsslice
 
 import (