Update and format package-level comments. (#258)

* Update version

* Fix grammar and style.

* Update and format packages' documentation.

README.md

@@ -6,16 +6,16 @@
 
 *Go Service Library*
 
-This Open Source project contains a collection of high-quality [GO](https://go.dev/) (golang) packages.
+This open-source project contains a collection of high-quality [Go](https://go.dev/) (Golang) packages.
 
-Each package follows common conventions and they can be individually imported in any project.
+Each package follows common conventions and can be individually imported into any project.
 
-This package collection forms the base structure for fully-fledged production-ready web-services.
+This package collection forms the base structure for fully-fledged, production-ready web services.
 
-A new Web service can be generated by using the command `make project CONFIG=project.cfg`.
-The new generated project name, description, etc..., can be set in the file specified via the CONFIG parameter.
+A new web service can be generated by using the command `make project CONFIG=project.cfg`.
+The newly generated project's name, description, etc., can be set in the file specified via the CONFIG parameter.
 
-The packages documentation is available at: [https://pkg.go.dev/github.com/Vonage/gosrvlib/](https://pkg.go.dev/github.com/Vonage/gosrvlib)
+The package documentation is available at: [https://pkg.go.dev/github.com/Vonage/gosrvlib/](https://pkg.go.dev/github.com/Vonage/gosrvlib/)
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/Vonage/gosrvlib.svg)](https://pkg.go.dev/github.com/Vonage/gosrvlib)   
 [![check](https://github.com/Vonage/gosrvlib/actions/workflows/check.yaml/badge.svg)](https://github.com/Vonage/gosrvlib/actions/workflows/check.yaml)
@@ -52,18 +52,17 @@ The packages documentation is available at: [https://pkg.go.dev/github.com/Vonag
 
 To quickly get started with this project, follow these steps:
 
-1. Ensure you have installed the latest Go version and Python3 for some extra tests.
-1. Clone the repository: `git clone https://github.com/Vonage/gosrvlib.git`.
-2. Change into the project directory: `cd gosrvlib`.
-3. Install the required dependencies and test everything: `DEVMODE=LOCAL make x`.
+1. Make sure you have installed the latest version of Go and Python3 for additional tests.
+2. Clone the repository: `git clone https://github.com/Vonage/gosrvlib.git`.
+3. Change to the project directory: `cd gosrvlib`.
+4. Install the required dependencies and test everything: `DEVMODE=LOCAL make x`.
 
 Now you are ready to start developing with gosrvlib!
 
+This project includes a *Makefile* that allows you to easily test and build the project on a Linux-compatible system using simple commands.
+All the artifacts and reports generated using this *Makefile* are stored in the *target* folder.
 
-This project includes a *Makefile* that allows you to test and build the project in a Linux-compatible system with simple commands.  
-All the artifacts and reports produced using this *Makefile* are stored in the *target* folder.  
-
-Alternatively, everything can be built inside a [Docker](https://www.docker.com) container using the command `make dbuild` that uses the environment defined at `resources/docker/Dockerfile.dev`.
+Alternatively, you can build everything inside a [Docker](https://www.docker.com) container using the command `make dbuild`, which utilizes the environment defined in `resources/docker/Dockerfile.dev`.
 
 To see all available options:
 ```bash

VERSION

@@ -1 +1 @@
-1.96.0
+1.96.1

examples/service/go.mod

@@ -7,7 +7,7 @@ toolchain go1.22.5
 replace github.com/Vonage/gosrvlib => ../..
 
 require (
-	github.com/Vonage/gosrvlib v1.96.0
+	github.com/Vonage/gosrvlib v1.96.1
 	github.com/golang/mock v1.6.0
 	github.com/jstemmer/go-junit-report/v2 v2.1.0
 	github.com/prometheus/client_golang v1.19.1

pkg/awsopt/awsopt.go

@@ -1,7 +1,12 @@
 /*
-Package awsopt provides functions to configure common AWS options for the official aws-sdk-go-v2 library.
-
-These common options can be easily used with other AWS-based packages in this library, such as s3 and sqs.
+Package awsopt provides functions to configure common AWS options for the
+official aws-sdk-go-v2 library.
+
+These common options can be easily used with other AWS-based packages in this
+library:
+  - awssecretcache
+  - s3
+  - sqs
 */
 package awsopt
 

pkg/awssecretcache/awssecretcache.go

@@ -1,12 +1,29 @@
 /*
-Package awssecretcache provides a simple client to retrieve and cache secrets from AWS Secrets Manager.
-To improve speed and reduce costs, the client uses a thread-safe local single-flight cache
-that avoids duplicate calls for the same secret.
-The cache has a maximum size and a time-to-live (TTL) for each entry.
-Duplicate calls for the same secret will wait for the first lookup to complete and return the same value.
+Package awssecretcache provides a simple client for retrieving and caching
+secrets from AWS Secrets Manager.
 
-This package is based on the official aws-sdk-go-v2 library.
+This package is based on the official aws-sdk-go-v2 library
+(https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager) and
+implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local,
+thread-safe, fixed-size, and single-flight cache for AWS Secrets lookup calls.
 
-Reference: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager.
+By caching previous values, awssecretcache improves the performance of secrets
+lookup by eliminating the need for repeated expensive requests.
+
+This package provides a local in-memory cache with a configurable maximum number
+of entries. The fixed size helps with efficient memory management and prevents
+excessive memory usage. The cache is thread-safe, allowing concurrent access
+without the need for external synchronization. It efficiently handles concurrent
+requests by sharing results from the first lookup, ensuring that only one
+request makes the expensive call, and avoiding unnecessary network load or
+resource starvation. Duplicate calls for the same key will wait for the first
+call to complete and return the same value.
+
+Each cache entry has a set time-to-live (TTL), so it will automatically expire.
+However, it is also possible to force the removal of a specific entry or reset
+the entire cache.
+
+This package is ideal for any Go application that heavily relies on AWS Secrets
+lookups.
 */
 package awssecretcache

pkg/bootstrap/bootstrap.go

@@ -1,6 +1,6 @@
 /*
-Package bootstrap provides a simple way to bootstrap an application with
-managed configuration, logging, metrics, application context, and shutdown signals.
+Package bootstrap provides a simple way to bootstrap an application with managed
+configuration, logging, metrics, application context, and shutdown signals.
 
 For an implementation example see in order:
   - examples/service/cmd/main.go

pkg/config/config.go

@@ -1,34 +1,50 @@
 /*
-Package config handles the configuration of a program.
-The configuration contains the set of initial parameter settings that are read at runtime by the program.
+Package config handles the configuration of a program. The configuration
+contains the set of initial parameter settings that are read at runtime by the
+program.
 
-This package allows plugging a fully-fledged configuration system into an application, taking care of the boilerplate code, common settings, configuration loading, and validation.
+This package allows plugging a fully-fledged configuration system into an
+application, taking care of the boilerplate code, common settings, configuration
+loading, and validation.
 
-Different configuration sources can be used during development, debugging, testing, or deployment.
-The configuration can be loaded from a local file, environment variables, or a remote configuration provider (e.g., Consul, etcd, etcd3, Firestore, NATS).
+Different configuration sources can be used during development, debugging,
+testing, or deployment. The configuration can be loaded from a local file,
+environment variables, or a remote configuration provider (e.g., Consul, etcd,
+etcd3, Firestore, NATS).
 
-This is a Viper-based implementation of the configuration model described in the following article:
-  - Nicola Asuni, 2014-09-13, "Software Configuration", https://technick.net/guides/software/software_configuration/
+This is a Viper-based implementation of the configuration model described in the
+following article:
+  - Nicola Asuni, 2014-09-13, "Software Configuration",
+    https://technick.net/guides/software/software_configuration/
 
 # Configuration Loading Strategy:
 
-To achieve maximum flexibility, the different configuration entry points are coordinated in the following sequence (1 has the lowest priority and 5 has the highest):
+To achieve maximum flexibility, the different configuration entry points are
+coordinated in the following sequence (1 has the lowest priority and 5 has the
+highest):
 
- 1. In the "myprog" program, the configuration parameters are defined as a data structure that can be easily mapped to and from a JSON object (or any other format supported by Viper like TOML, YAML, and HCL).
-    Each structure parameter is annotated with the "mapstructure" and "validate" tags to define the name mapping and the validation rules.
-    The parameters are initialized with constant default values.
+ 1. In the "myprog" program, the configuration parameters are defined as a data
+    structure that can be easily mapped to and from a JSON object (or any other
+    format supported by Viper like TOML, YAML, and HCL). Each structure
+    parameter is annotated with the "mapstructure" and "validate" tags to define
+    the name mapping and the validation rules. The parameters are initialized
+    with constant default values.
 
- 2. The program attempts to load the local "config.json" configuration file, and as soon as one is found, it overwrites the default values previously set.
+ 2. The program attempts to load the local "config.json" configuration file, and
+    as soon as one is found, it overwrites the default values previously set.
 
-    The configuration file is searched in the following ordered directories based on the Linux Filesystem Hierarchy Standard (FHS):
+    The configuration file is searched in the following ordered directories
+    based on the Linux Filesystem Hierarchy Standard (FHS):
 
     - ./
 
     - ~/.myprog/
 
     - /etc/myprog/
 
- 3. The program attempts to load the environmental variables that define the remote configuration system. If found, it overwrites the corresponding configuration parameters:
+ 3. The program attempts to load the environmental variables that define the
+    remote configuration system. If found, it overwrites the corresponding
+    configuration parameters:
 
     - [ENVIRONMENT VARIABLE NAME] → [CONFIGURATION PARAMETER NAME]
 
@@ -42,22 +58,30 @@ To achieve maximum flexibility, the different configuration entry points are coo
 
     - MYPROG_REMOTECONFIGDATA → remoteConfigData
 
- 4. If the "remoteConfigProvider" parameter is not empty, the program attempts to load the configuration data from the specified source.
-    This can be any remote source supported by the Viper library (e.g., Consul, etcd, etcd3, Firestore, NATS).
-    The configuration source can also be the "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".
+ 4. If the "remoteConfigProvider" parameter is not empty, the program attempts
+    to load the configuration data from the specified source. This can be any
+    remote source supported by the Viper library (e.g., Consul, etcd, etcd3,
+    Firestore, NATS). The configuration source can also be the
+    "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when
+    "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".
 
- 5. Any specified command-line argument overwrites the corresponding configuration parameter.
+ 5. Any specified command-line argument overwrites the corresponding
+    configuration parameter.
 
  6. The configuration parameters are validated via the Validate() function.
 
 # Example:
 
-  - An implementation example of this configuration package can be found in examples/service/internal/cli/config.go
-    Note that the "log", "shutdown_timeout", and "remoteConfig" parameters are defined in this package as they are common to all programs.
+  - An implementation example of this configuration package can be found in
+    examples/service/internal/cli/config.go Note that the "log",
+    "shutdown_timeout", and "remoteConfig" parameters are defined in this
+    package as they are common to all programs.
 
-  - The configuration file format of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.schema.json
+  - The configuration file format of the example service is defined by
+    examples/service/resources/etc/gosrvlibexample/config.schema.json
 
-  - The default configuration file of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.json
+  - The default configuration file of the example service is defined by
+    examples/service/resources/etc/gosrvlibexample/config.json
 */
 package config
 

pkg/decint/decint.go

@@ -1,7 +1,9 @@
 /*
-Package decint provides utility functions to parse and represent decimal values as integers with a set precision.
+Package decint provides utility functions to parse and represent decimal values
+as integers with a set precision.
 
-The functions in this package are typically used to store and retrieve small currency values without loss of precision.
+The functions in this package are typically used to store and retrieve small
+currency values without loss of precision.
 
 Safe decimal values are limited up to 2^53 / 1e+6 = 9_007_199_254.740_992.
 */

pkg/dnscache/dnscache.go

@@ -1,7 +1,28 @@
 /*
-Package dnscache provides a thread-safe local single-flight DNS cache for LookupHost.
-The cache has a maximum size and a time-to-live (TTL) for each DNS entry.
-Duplicate LookupHost calls for the same host will wait for the first lookup to complete and return the same value.
+Package dnscache implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a
+simple, local, thread-safe, fixed-size, and single-flight cache for DNS lookup
+calls.
+
+This package provides LookupHost() and DialContext() functions that can be used
+in place of the standard ones in the net package.
+
+By caching previous values, dnscache improves DNS lookup performance by
+eliminating the need for repeated expensive requests.
+
+This package provides a local in-memory cache with a configurable maximum number
+of entries. The fixed size helps with efficient memory management and prevents
+excessive memory usage. The cache is thread-safe, allowing concurrent access
+without the need for external synchronization. It efficiently handles concurrent
+requests by sharing results from the first lookup, ensuring only one request
+does the expensive call, and avoiding unnecessary network load or resource
+starvation. Duplicate calls for the same key will wait for the first call to
+complete and return the same value.
+
+Each cache entry has a set time-to-live (TTL), so it will automatically expire.
+However, it is also possible to force the removal of a specific DNS entry or
+reset the entire cache.
+
+This package is ideal for any Go application that relies heavily on DNS lookups.
 */
 package dnscache
 

pkg/encode/encode.go

@@ -1,6 +1,7 @@
 /*
-Package encode provides serialization and deserialization functions to safely transmit,
-store and retrieve data between different systems (e.g., databases, queues, caches, etc.).
+Package encode provides a collection of functions for safe serialization and
+deserialization of data between different systems, such as databases, queues,
+and caches.
 */
 package encode
 

pkg/encrypt/encrypt.go

@@ -1,5 +1,7 @@
 /*
-Package encrypt contains a collection of utility functions to encrypt and decrypt data.
+Package encrypt provides a collection of functions for safe encryption and
+decryption of data between different systems, such as databases, queues, and
+caches.
 */
 package encrypt
 

pkg/enumbitmap/enumbitmap.go

@@ -1,9 +1,11 @@
 /*
-Package enumbitmap provides functions to encode slices of enumeration strings into integer bitmap values and vice versa.
+Package enumbitmap provides functions to encode slices of enumeration strings
+into integer bitmap values and vice versa.
 
-Each bit correspond to a unique enumeration value.
+Each bit correspond to a unique enumeration value. It supports maximum 32 bit
+(33 distinct values including NONE).
 
-# Example:
+# Example with 8 bits:
 
 	00000000 =   0 dec = NONE
 	00000001 =   1 dec = FIRST

pkg/enumcache/enumcache.go

@@ -1,6 +1,8 @@
 /*
-Package enumcache provides simple thread-safe methods to store and retrieve enumeration sets with an integer ID and string name.
-It includes support for binary maps (enumbitmap), where each bit represents a different name in the enumeration set.
+Package enumcache provides a collection of thread-safe methods for storing and
+retrieving enumeration sets with integer IDs and string names. It includes
+support for binary maps (github.com/Vonage/gosrvlib/pkg/enumbitmap), where each
+bit represents a different name in the enumeration set.
 */
 package enumcache
 

pkg/enumdb/enumdb.go

@@ -1,9 +1,11 @@
 /*
-Package enumdb allows to load enumeration sets (enumcache) from multiple database tables.
+Package enumdb allows loading enumeration sets
+(github.com/Vonage/gosrvlib/pkg/enumcache) from multiple database tables.
 
-Each enumeration has a numerical ID ("id" on the database table as primary key) and a string name ("name" on the database table as unique string).
+Each enumeration has a numerical ID ("id" on the database table as the primary
+key) and a string name ("name" on the database table as a unique string).
 
-Example of MySQL database table that can be used with this package:
+Example of a MySQL database table that can be used with this package:
 
 	CREATE TABLE IF NOT EXISTS `example` (
 	  `id` SMALLINT UNSIGNED NOT NULL,

pkg/errtrace/trace.go

@@ -1,5 +1,7 @@
 /*
-Package errtrace provides a function to automatically trace errors.
+Package errtrace provides a function to automatically trace Go errors. Each
+error is annotated with the filename, line number, and function name where it
+was created.
 */
 package errtrace
 
@@ -8,7 +10,7 @@ import (
 	"runtime"
 )
 
-// Trace annotates the error message with the filename, line number and function name.
+// Trace annotates the error message with the filename, line number, and function name.
 func Trace(err error) error {
 	if err == nil {
 		return nil

pkg/exttools/exttools.go

@@ -1,9 +1,9 @@
 //go:build exttools
 
 /*
-Package exttools lists external build and test tools.
-These tools will appear in the `go.mod` file, but will not be a part of the build.
-They will be also excluded from the binaries as the "exttools" tag is not used.
+Package exttools lists external build and test tools. These tools will appear in
+the `go.mod` file but will not be included in the build process. They will also
+be excluded from the binaries since the "exttools" tag is not used.
 */
 package exttools