docs: add package-level doc comments

Provide Go-style doc comments for the password hasher API, Argon2id implementation, internal PHC helpers, and comparison utility so exported symbols are self-describing. This clarifies default configuration behavior, registry wiring, and PHC encoding expectations without altering runtime behavior.

Author: allisson

argon2/argon2id.go

@@ -11,6 +11,7 @@ import (
 	"github.com/allisson/go-pwdhash/internal/subtle"
 )
 
+// Argon2idHasher wraps parameterized Argon2id hashing operations.
 type Argon2idHasher struct {
 	Memory      uint32
 	Iterations  uint32
@@ -19,6 +20,7 @@ type Argon2idHasher struct {
 	KeyLength   uint32
 }
 
+// Default returns an Argon2idHasher configured with library defaults.
 func Default() *Argon2idHasher {
 	return &Argon2idHasher{
 		Memory:      64 * 1024,
@@ -29,10 +31,12 @@ func Default() *Argon2idHasher {
 	}
 }
 
+// ID reports the PHC algorithm identifier.
 func (a *Argon2idHasher) ID() string {
 	return "argon2id"
 }
 
+// Hash derives an Argon2id key and returns the PHC string.
 func (a *Argon2idHasher) Hash(password []byte) (string, error) {
 	salt := make([]byte, a.SaltLength)
 	if _, err := rand.Read(salt); err != nil {
@@ -63,6 +67,7 @@ func (a *Argon2idHasher) Hash(password []byte) (string, error) {
 	return enc.String(), nil
 }
 
+// Verify recomputes the Argon2id hash and compares it in constant time.
 func (a *Argon2idHasher) Verify(password []byte, encoded string) (bool, error) {
 	parsed, err := encoding.Parse(encoded)
 	if err != nil {
@@ -85,6 +90,7 @@ func (a *Argon2idHasher) Verify(password []byte, encoded string) (bool, error) {
 	return subtle.ConstantTimeCompare(key, parsed.Hash), nil
 }
 
+// NeedsRehash reports whether the encoded parameters diverge from the current configuration.
 func (a *Argon2idHasher) NeedsRehash(encoded string) (bool, error) {
 	parsed, err := encoding.Parse(encoded)
 	if err != nil {

errors.go

@@ -3,5 +3,6 @@ package pwdhash
 import "errors"
 
 var (
+	// ErrInvalidHash indicates that an encoded hash cannot be parsed.
 	ErrInvalidHash = errors.New("invalid encoded hash")
 )

hasher.go

@@ -1,5 +1,6 @@
 package pwdhash
 
+// Hasher represents a password hashing algorithm implementation.
 type Hasher interface {
 	ID() string
 	Hash(password []byte) (string, error)

internal/encoding/parse.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 )
 
+// Parse decodes a PHC-formatted string into an EncodedHash structure.
 func Parse(s string) (*EncodedHash, error) {
 	parts := strings.Split(s, "$")
 	if len(parts) < 6 {

internal/encoding/phc.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 )
 
+// EncodedHash captures a PHC-formatted hash and associated metadata.
 type EncodedHash struct {
 	Algorithm string
 	Version   int
@@ -14,6 +15,7 @@ type EncodedHash struct {
 	Hash      []byte
 }
 
+// String renders the hash in PHC string format.
 func (e EncodedHash) String() string {
 	params := []string{}
 	for k, v := range e.Params {

internal/subtle/compare.go

@@ -2,6 +2,7 @@ package subtle
 
 import "crypto/subtle"
 
+// ConstantTimeCompare matches slices while avoiding timing leaks.
 func ConstantTimeCompare(a, b []byte) bool {
 	if len(a) != len(b) {
 		return false

options.go

@@ -2,18 +2,22 @@ package pwdhash
 
 import "github.com/allisson/go-pwdhash/argon2"
 
+// config holds PasswordHasher construction settings.
 type config struct {
 	current Hasher
 }
 
+// Option configures PasswordHasher construction.
 type Option func(*config)
 
+// defaultConfig initializes a config with the default Argon2id hasher.
 func defaultConfig() *config {
 	return &config{
 		current: argon2.Default(),
 	}
 }
 
+// WithHasher overrides the default hashing algorithm.
 func WithHasher(h Hasher) Option {
 	return func(c *config) {
 		c.current = h

password.go

@@ -6,11 +6,13 @@ import (
 	"github.com/allisson/go-pwdhash/internal/encoding"
 )
 
+// PasswordHasher manages password hashing operations via registered algorithms.
 type PasswordHasher struct {
 	current  Hasher
 	registry map[string]Hasher
 }
 
+// New constructs a PasswordHasher configured via the provided options.
 func New(opts ...Option) (*PasswordHasher, error) {
 	cfg := defaultConfig()
 
@@ -27,10 +29,12 @@ func New(opts ...Option) (*PasswordHasher, error) {
 	}, nil
 }
 
+// Hash encodes the provided password using the active hasher.
 func (p *PasswordHasher) Hash(password []byte) (string, error) {
 	return p.current.Hash(password)
 }
 
+// Verify checks whether the encoded hash matches the provided password.
 func (p *PasswordHasher) Verify(password []byte, encoded string) (bool, error) {
 	parsed, err := encoding.Parse(encoded)
 	if err != nil {
@@ -45,6 +49,7 @@ func (p *PasswordHasher) Verify(password []byte, encoded string) (bool, error) {
 	return hasher.Verify(password, encoded)
 }
 
+// NeedsRehash reports whether the encoded hash should be regenerated.
 func (p *PasswordHasher) NeedsRehash(encoded string) (bool, error) {
 	parsed, err := encoding.Parse(encoded)
 	if err != nil {