chore: add more comments ( PR #50)

README.md

@@ -1,7 +1,7 @@
 # go-totp
 
 [![go1.22+](https://img.shields.io/badge/Go-1.22+-blue?logo=go)](https://github.com/KEINOS/go-totp/blob/main/.github/workflows/unit-tests.yml#L81 "Supported versions")
-[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/ "View document")
+[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/totp "View document")
 
 `go-totp` is a simple Go package to implement [Timebased-One-Time-Password](https://en.wikipedia.org/wiki/Time-based_one-time_password) authentication functionality, a.k.a. `TOTP`, to the Go app.
 

totp/algorithm.go

@@ -11,15 +11,19 @@ import (
 //  Type: Algorithm
 // ----------------------------------------------------------------------------
 
-// Algorithm is a string that represents the algorithm used for HMAC.
+// Algorithm is a string that represents the algorithm used to generate the
+// passcode (for HMAC).
 type Algorithm string
 
 // ----------------------------------------------------------------------------
 //  Constructor
 // ----------------------------------------------------------------------------
 
-// NewAlgorithmStr creates a new Algorithm object from a string.
-// Choices of algo are: MD5, SHA1, SHA256 and SHA512.
+// NewAlgorithmStr creates a new Algorithm object from a string that is used to
+// generate the passcode.
+// Choices of algo are:
+//
+//	MD5, SHA1, SHA256 and SHA512.
 func NewAlgorithmStr(algo string) (Algorithm, error) {
 	const (
 		cMD5    = "MD5"
@@ -39,6 +43,9 @@ func NewAlgorithmStr(algo string) (Algorithm, error) {
 }
 
 // NewAlgorithmID creates a new Algorithm object from an int.
+//
+// It is not an usual way to create an Algorithm object. It is used to convert
+// the ID of the algorithm to the Algorithm object for checking purposes.
 func NewAlgorithmID(algoID int) (Algorithm, error) {
 	const (
 		cMD5    = "MD5"

totp/example_test.go

@@ -16,6 +16,10 @@ import (
 //  Package Examples
 // ============================================================================
 
+// This example demonstrates how to generate a new secret key with default
+// options and validate the passcode.
+//
+// The generated key should be compatible with most TOTP authenticator apps.
 func Example() {
 	Issuer := "Example.com"            // name of the service
 	AccountName := "[email protected]" // name of the user
@@ -54,12 +58,19 @@ func Example() {
 	// * Validation result: Passcode is valid
 }
 
+// This example demonstrates how to generate a new secret key with custom options
+// and validate the passcode.
+//
+// Since most TOTP authenticator apps are based on SHA1 hashing algorithm to
+// generate the passcode, this example is useful when you need to generate the
+// passcode with a stronger hash algorithm such as SHA256 and SHA512.
 func Example_custom() {
 	// Generate a new secret key with custom options
 	Issuer := "Example.com"
 	AccountName := "[email protected]"
 
 	key, err := totp.GenerateKey(Issuer, AccountName,
+		// Algorithm choices are: MD5, SHA1, SHA256 and SHA512.
 		totp.WithAlgorithm(totp.Algorithm("SHA256")),
 		totp.WithPeriod(15),
 		totp.WithSecretSize(256),
@@ -121,7 +132,8 @@ func Example_advanced() {
 // ============================================================================
 
 func ExampleAlgorithm() {
-	// Create a new Algorithm object from a string. Choices are:
+	// Create a new Algorithm object from a string for passcode generation.
+	// Choices are:
 	//   MD5, SHA1, SHA256 and SHA512.
 	algo, err := totp.NewAlgorithmStr("SHA512")
 	if err != nil {
@@ -139,7 +151,7 @@ func ExampleAlgorithm() {
 }
 
 func ExampleAlgorithm_IsSupported() {
-	// Set unsupported algorithm
+	// Set unsupported algorithm for passcode generation
 	algo := totp.Algorithm("BLAKE3")
 
 	// Check if the algorithm is supported

totp/totp.go

@@ -4,6 +4,16 @@ authentication functionality, a.k.a. `TOTP`, to the Go app.
 
 Optionally, it supports ECDH key agreement protocol to share the same secret key
 between two parties.
+
+```shellsession
+# Install the module
+go get github.com/KEINOS/go-totp
+```
+
+```go
+// Use the package
+import "github.com/KEINOS/go-totp/totp"
+```
 */
 package totp