Update UnmarshalMaxMindDB docs

And make them more accurate.

Author: oschwald

example_test.go

@@ -6,6 +6,7 @@ import (
 	"net/netip"
 
 	"github.com/oschwald/maxminddb-golang/v2"
+	"github.com/oschwald/maxminddb-golang/v2/mmdbdata"
 )
 
 // This example shows how to decode to a struct.
@@ -139,16 +140,16 @@ func ExampleReader_NetworksWithin() {
 }
 
 // CustomCity represents a simplified city record with custom unmarshaling.
-// This demonstrates the Unmarshaler interface for high-performance decoding.
+// This demonstrates the Unmarshaler interface for custom decoding.
 type CustomCity struct {
 	Names     map[string]string
 	GeoNameID uint
 }
 
-// UnmarshalMaxMindDB implements the maxminddb.Unmarshaler interface.
-// This provides significant performance improvements over reflection-based decoding
-// by allowing custom, optimized decoding logic for performance-critical applications.
-func (c *CustomCity) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
+// UnmarshalMaxMindDB implements the mmdbdata.Unmarshaler interface.
+// This provides custom decoding logic, similar to how json.Unmarshaler works
+// with encoding/json, allowing fine-grained control over data processing.
+func (c *CustomCity) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
 	for key, err := range d.ReadMap() {
 		if err != nil {
 			return err
@@ -198,9 +199,9 @@ func (c *CustomCity) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
 	return nil
 }
 
-// This example demonstrates how to use the Unmarshaler interface for high-performance
-// custom decoding. Types implementing Unmarshaler automatically use custom decoding
-// logic instead of reflection, providing better performance for critical applications.
+// This example demonstrates how to use the Unmarshaler interface for custom decoding.
+// Types implementing Unmarshaler automatically use custom decoding logic instead of
+// reflection, similar to how json.Unmarshaler works with encoding/json.
 func ExampleUnmarshaler() {
 	db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
 	if err != nil {

decoder.go renamed to mmdbdata/doc.go

@@ -1,23 +1,19 @@
-package maxminddb
-
-import "github.com/oschwald/maxminddb-golang/v2/mmdbdata"
-
-// Decoder provides methods for decoding MaxMind DB data values.
-// This interface is passed to UnmarshalMaxMindDB methods to allow
-// custom decoding logic that avoids reflection for performance-critical applications.
+// Package mmdbdata provides low-level types and interfaces for custom MaxMind DB decoding.
 //
-// Types implementing Unmarshaler will automatically use custom decoding logic
-// instead of reflection when used with Reader.Lookup, providing better performance
-// for performance-critical applications.
+// This package allows custom decoding logic for applications that need fine-grained
+// control over how MaxMind DB data is processed. For most use cases, the high-level
+// maxminddb.Reader API is recommended instead.
+//
+// # Manual Decoding Example
 //
-// Example:
+// Custom types can implement the Unmarshaler interface for custom decoding:
 //
 //	type City struct {
 //		Names     map[string]string `maxminddb:"names"`
 //		GeoNameID uint              `maxminddb:"geoname_id"`
 //	}
 //
-//	func (c *City) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
+//	func (c *City) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
 //		for key, err := range d.ReadMap() {
 //			if err != nil { return err }
 //			switch string(key) {
@@ -40,8 +36,18 @@ import "github.com/oschwald/maxminddb-golang/v2/mmdbdata"
 //		}
 //		return nil
 //	}
-type Decoder = mmdbdata.Decoder
-
-// Unmarshaler is implemented by types that can unmarshal MaxMind DB data.
-// This follows the same pattern as json.Unmarshaler and other Go standard library interfaces.
-type Unmarshaler = mmdbdata.Unmarshaler
+//
+// Types implementing Unmarshaler will automatically use custom decoding logic
+// instead of reflection when used with maxminddb.Reader.Lookup, similar to how
+// json.Unmarshaler works with encoding/json.
+//
+// # Direct Decoder Usage
+//
+// For even more control, you can use the Decoder directly:
+//
+//	decoder := mmdbdata.NewDecoder(buffer, offset)
+//	value, err := decoder.ReadString()
+//	if err != nil {
+//		return err
+//	}
+package mmdbdata

reader.go

@@ -55,22 +55,24 @@
 // For maximum performance in high-throughput applications, consider:
 //
 //  1. Using custom struct types that only include the fields you need
-//  2. Implementing the Unmarshaler interface for zero-allocation decoding
+//  2. Implementing the Unmarshaler interface for custom decoding
 //  3. Reusing the Reader instance across multiple goroutines (it's thread-safe)
 //
 // # Custom Unmarshaling
 //
-// For performance-critical applications, you can implement the Unmarshaler
-// interface to avoid reflection overhead:
+// For custom decoding logic, you can implement the mmdbdata.Unmarshaler interface,
+// similar to how encoding/json's json.Unmarshaler works. Types implementing this
+// interface will automatically use custom decoding logic when used with Reader.Lookup:
 //
 //	type FastCity struct {
 //		CountryISO string
 //		CityName   string
 //	}
 //
-//	func (c *FastCity) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
+//	func (c *FastCity) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
 //		// Custom decoding logic using d.ReadMap(), d.ReadString(), etc.
-//		// See ExampleUnmarshaler for a complete implementation
+//		// Allows fine-grained control over how MaxMind DB data is decoded
+//		// See mmdbdata package documentation and ExampleUnmarshaler for complete examples
 //	}
 //
 // # Network Iteration

reader_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/oschwald/maxminddb-golang/v2/internal/mmdberrors"
+	"github.com/oschwald/maxminddb-golang/v2/mmdbdata"
 )
 
 func TestReader(t *testing.T) {
@@ -1061,7 +1062,7 @@ type TestCity struct {
 
 // UnmarshalMaxMindDB implements the Unmarshaler interface for TestCity.
 // This demonstrates custom decoding that avoids reflection for better performance.
-func (c *TestCity) UnmarshalMaxMindDB(d *Decoder) error {
+func (c *TestCity) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
 	for key, err := range d.ReadMap() {
 		if err != nil {
 			return err
@@ -1105,7 +1106,7 @@ type TestASN struct {
 }
 
 // UnmarshalMaxMindDB implements the Unmarshaler interface for TestASN.
-func (a *TestASN) UnmarshalMaxMindDB(d *Decoder) error {
+func (a *TestASN) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
 	for key, err := range d.ReadMap() {
 		if err != nil {
 			return err