Improve Metadata and Verify documentation

- Add comprehensive field documentation to Metadata struct with
  references to MaxMind DB specification
- Add BuildTime() convenience method to convert BuildEpoch to time.Time
- Enhance Verify() documentation explaining validation scope and use cases
- Add ExampleReader_Verify showing verification and metadata access
- Add TestMetadataBuildTime to verify BuildTime() method correctness

Author: oschwald

example_test.go

@@ -102,6 +102,39 @@ func ExampleReader_Networks() {
 	// 2003::/24: Cable/DSL
 }
 
+// This example demonstrates how to validate a MaxMind DB file and access metadata.
+func ExampleReader_Verify() {
+	db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close() //nolint:errcheck // error doesn't matter
+
+	// Verify database integrity
+	if err := db.Verify(); err != nil {
+		log.Printf("Database validation failed: %v", err)
+		return
+	}
+
+	// Access metadata information
+	metadata := db.Metadata
+	fmt.Printf("Database type: %s\n", metadata.DatabaseType)
+	fmt.Printf("Build time: %s\n", metadata.BuildTime().Format("2006-01-02 15:04:05"))
+	fmt.Printf("IP version: IPv%d\n", metadata.IPVersion)
+	fmt.Printf("Languages: %v\n", metadata.Languages)
+
+	if desc, ok := metadata.Description["en"]; ok {
+		fmt.Printf("Description: %s\n", desc)
+	}
+
+	// Output:
+	// Database type: GeoIP2-City
+	// Build time: 2022-07-26 07:53:10
+	// IP version: IPv6
+	// Languages: [en zh]
+	// Description: GeoIP2 City Test Database (fake GeoIP2 data, for example purposes only)
+}
+
 // This example demonstrates how to iterate over all networks in the
 // database which are contained within an arbitrary network.
 func ExampleReader_NetworksWithin() {

mmdbdata/doc.go

@@ -50,4 +50,4 @@
 //	if err != nil {
 //		return err
 //	}
-package mmdbdata
+package mmdbdata

reader.go

@@ -112,6 +112,7 @@ import (
 	"net/netip"
 	"os"
 	"runtime"
+	"time"
 
 	"github.com/oschwald/maxminddb-golang/v2/internal/decoder"
 	"github.com/oschwald/maxminddb-golang/v2/internal/mmdberrors"
@@ -137,20 +138,62 @@ type Reader struct {
 	hasMappedFile     bool
 }
 
-// Metadata holds the metadata decoded from the MaxMind DB file. In particular
-// it has the format version, the build time as Unix epoch time, the database
-// type and description, the IP version supported, and a slice of the natural
-// languages included.
+// Metadata holds the metadata decoded from the MaxMind DB file.
+//
+// Key fields include:
+//   - DatabaseType: indicates the structure of data records (e.g., "GeoIP2-City")
+//   - Description: localized descriptions in various languages
+//   - Languages: locale codes for which the database may contain localized data
+//   - BuildEpoch: database build timestamp as Unix epoch seconds
+//   - IPVersion: supported IP version (4 for IPv4-only, 6 for IPv4/IPv6)
+//   - NodeCount: number of nodes in the search tree
+//   - RecordSize: size in bits of each record in the search tree (24, 28, or 32)
+//
+// For detailed field descriptions, see the MaxMind DB specification:
+// https://maxmind.github.io/MaxMind-DB/
 type Metadata struct {
-	Description              map[string]string `maxminddb:"description"`
-	DatabaseType             string            `maxminddb:"database_type"`
-	Languages                []string          `maxminddb:"languages"`
-	BinaryFormatMajorVersion uint              `maxminddb:"binary_format_major_version"`
-	BinaryFormatMinorVersion uint              `maxminddb:"binary_format_minor_version"`
-	BuildEpoch               uint              `maxminddb:"build_epoch"`
-	IPVersion                uint              `maxminddb:"ip_version"`
-	NodeCount                uint              `maxminddb:"node_count"`
-	RecordSize               uint              `maxminddb:"record_size"`
+	// Description contains localized database descriptions.
+	// Keys are language codes (e.g., "en", "zh-CN"), values are UTF-8 descriptions.
+	Description map[string]string `maxminddb:"description"`
+
+	// DatabaseType indicates the structure of data records associated with IP addresses.
+	// Names starting with "GeoIP" are reserved for MaxMind databases.
+	DatabaseType string `maxminddb:"database_type"`
+
+	// Languages lists locale codes for which this database may contain localized data.
+	// Records should not contain localized data for locales not in this array.
+	Languages []string `maxminddb:"languages"`
+
+	// BinaryFormatMajorVersion is the major version of the MaxMind DB binary format.
+	// Current supported version is 2.
+	BinaryFormatMajorVersion uint `maxminddb:"binary_format_major_version"`
+
+	// BinaryFormatMinorVersion is the minor version of the MaxMind DB binary format.
+	// Current supported version is 0.
+	BinaryFormatMinorVersion uint `maxminddb:"binary_format_minor_version"`
+
+	// BuildEpoch contains the database build timestamp as Unix epoch seconds.
+	// Use BuildTime() method for a time.Time representation.
+	BuildEpoch uint `maxminddb:"build_epoch"`
+
+	// IPVersion indicates the IP version support:
+	//   4: IPv4 addresses only
+	//   6: Both IPv4 and IPv6 addresses (IPv4 addresses are represented as IPv4-mapped IPv6)
+	IPVersion uint `maxminddb:"ip_version"`
+
+	// NodeCount is the number of nodes in the search tree.
+	NodeCount uint `maxminddb:"node_count"`
+
+	// RecordSize is the size in bits of each record in the search tree.
+	// Valid values are 24, 28, or 32.
+	RecordSize uint `maxminddb:"record_size"`
+}
+
+// BuildTime returns the database build time as a time.Time.
+// This is a convenience method that converts the BuildEpoch field
+// from Unix epoch seconds to a time.Time value.
+func (m Metadata) BuildTime() time.Time {
+	return time.Unix(int64(m.BuildEpoch), 0)
 }
 
 type readerOptions struct{}

reader_test.go

@@ -1156,3 +1156,27 @@ func TestFallbackToReflection(t *testing.T) {
 	// Log the result for verification
 	t.Logf("Reflection fallback result: %+v", regularStruct)
 }
+
+func TestMetadataBuildTime(t *testing.T) {
+	reader, err := Open(testFile("GeoIP2-City-Test.mmdb"))
+	require.NoError(t, err)
+	defer func() {
+		if err := reader.Close(); err != nil {
+			t.Errorf("Error closing reader: %v", err)
+		}
+	}()
+
+	metadata := reader.Metadata
+
+	// Test that BuildTime() returns a valid time
+	buildTime := metadata.BuildTime()
+	assert.False(t, buildTime.IsZero(), "BuildTime should not be zero")
+
+	// Test that BuildTime() matches BuildEpoch
+	expectedTime := time.Unix(int64(metadata.BuildEpoch), 0)
+	assert.Equal(t, expectedTime, buildTime, "BuildTime should match time.Unix(BuildEpoch, 0)")
+
+	// Verify the build time is reasonable (after 2010, before 2030)
+	assert.True(t, buildTime.After(time.Date(2010, 1, 1, 0, 0, 0, 0, time.UTC)))
+	assert.True(t, buildTime.Before(time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)))
+}

verifier.go

@@ -10,9 +10,23 @@ type verifier struct {
 	reader *Reader
 }
 
-// Verify checks that the database is valid. It validates the search tree,
-// the data section, and the metadata section. This verifier is stricter than
-// the specification and may return errors on databases that are readable.
+// Verify performs comprehensive validation of the MaxMind DB file.
+//
+// This method validates:
+//   - Metadata section: format versions, required fields, and value constraints
+//   - Search tree: traverses all networks to verify tree structure integrity
+//   - Data section separator: validates the 16-byte separator between tree and data
+//   - Data section: verifies all data records referenced by the search tree
+//
+// The verifier is stricter than the MaxMind DB specification and may return
+// errors on some databases that are still readable by normal operations.
+// This method is useful for:
+//   - Validating database files after download or generation
+//   - Debugging database corruption issues
+//   - Ensuring database integrity in critical applications
+//
+// Note: Verification traverses the entire database and may be slow on large files.
+// The method is thread-safe and can be called on an active Reader.
 func (r *Reader) Verify() error {
 	v := verifier{r}
 	if err := v.verifyMetadata(); err != nil {