docs: add godoc comments to all exported functions and methods

mc/data/biomes.go

@@ -28,6 +28,7 @@ type Biome struct {
 
 var BiomesCache = make(map[string][]*Biome)
 
+// BiomesForVersion returns the biome definitions for the given Minecraft version, caching them after the first load.
 func BiomesForVersion(v string) (ret []*Biome) {
 	var ok bool
 	if ret, ok = BiomesCache[v]; ok {
@@ -39,6 +40,7 @@ func BiomesForVersion(v string) (ret []*Biome) {
 	return b
 }
 
+// LookupBiomeById returns the biome with the given numeric ID in the given version.
 func LookupBiomeById(version string, id int32) (biome *Biome, ok bool) {
 	for _, b := range BiomesForVersion(version) {
 		if b.Id == id {
@@ -52,6 +54,7 @@ func LookupBiomeById(version string, id int32) (biome *Biome, ok bool) {
 
 var UnknownBiomeNameErr = errors.New("unknown biome Name")
 
+// LookupBiomeByName returns the biome with the given name in the given version.
 func LookupBiomeByName(version string, name string) (biome *Biome, ok bool) {
 	for _, b := range BiomesForVersion(version) {
 		if b.Name == name {

mc/data/blocks.go

@@ -59,6 +59,7 @@ type BlockState struct {
 var BlocksCache = make(map[string][]*Block)
 var BlocksCacheIdMap = make(map[string]map[int32]*Block)
 
+// BlocksForVersion returns the block definitions for the given Minecraft version, caching them after the first load.
 func BlocksForVersion(v string) (ret []*Block) {
 	var ok bool
 	if ret, ok = BlocksCache[v]; ok {
@@ -84,6 +85,7 @@ func BlocksForVersion(v string) (ret []*Block) {
 	return b
 }
 
+// LookupBlockByStateId returns the block for the given global palette state ID in the given version.
 func LookupBlockByStateId(version string, stateId int32) (block *Block, ok bool) {
 	idmap, found := BlocksCacheIdMap[version]
 	if !found {
@@ -101,6 +103,7 @@ func LookupBlockByStateId(version string, stateId int32) (block *Block, ok bool)
 
 var UnknownBlockNameErr = errors.New("unknown block Name")
 
+// LookupBlockByName returns the block with the given name in the given version.
 func LookupBlockByName(version string, name string) (block *Block, ok bool) {
 	for _, b := range BlocksForVersion(version) {
 		if b.Name == name {
@@ -111,6 +114,7 @@ func LookupBlockByName(version string, name string) (block *Block, ok bool) {
 	return
 }
 
+// StateIdFromBlocKAndStateMap returns the global palette state ID for the given block name and state property map in the given version.
 func StateIdFromBlocKAndStateMap(version string, name string, stateMap map[string]string) (stateId int32, err error) {
 	b, ok := LookupBlockByName(version, name)
 	if !ok {
@@ -135,6 +139,7 @@ var BadBlockStateTypeErr = errors.New("bad block state type")
 var BadEnumErr = errors.New("bad enum")
 var SupplyAllStatesErr = errors.New("supply all states")
 
+// FromBlockState converts a global palette state ID back into a block definition and a map of state properties.
 func FromBlockState(version string, stateId int32) (b *Block, stateData map[string]string, err error) {
 	b, ok := LookupBlockByStateId(version, stateId)
 	if !ok {

mc/data/data.go

@@ -12,6 +12,7 @@ import (
 //go:embed minecraft-data/pc minecraft-data/dataPaths.json
 var MinecraftData embed.FS
 
+// LoadJson reads a JSON file from the embedded minecraft-data FS and unmarshals it into data.
 func LoadJson(path string, data any) (err error) {
 	b, err := MinecraftData.ReadFile(path)
 	if err != nil {
@@ -21,6 +22,7 @@ func LoadJson(path string, data any) (err error) {
 	return
 }
 
+// LoadVersionedJson loads a version-specific JSON data file from the embedded minecraft-data FS and unmarshals it into data.
 func LoadVersionedJson(version, dataName string, data any) (err error) {
 	b, err := MinecraftData.ReadFile("minecraft-data/" + Paths.Data[version][dataName] + "/" + dataName + ".json")
 	if err != nil {

mc/data/item.go

@@ -19,6 +19,7 @@ type Item struct {
 var ItemsCache = make(map[string][]*Item)
 var ItemsCacheMutex = &sync.RWMutex{}
 
+// ItemsForVersion returns the item definitions for the given Minecraft version, caching them after the first load.
 func ItemsForVersion(v string) (ret []*Item) {
 	var ok bool
 	ItemsCacheMutex.RLock()
@@ -35,6 +36,7 @@ func ItemsForVersion(v string) (ret []*Item) {
 	return b
 }
 
+// LookupItemById returns the item with the given numeric ID in the given version.
 func LookupItemById(version string, id int32) (item *Item, ok bool) {
 	for _, i := range ItemsForVersion(version) {
 		if i.Id == id {
@@ -46,6 +48,7 @@ func LookupItemById(version string, id int32) (item *Item, ok bool) {
 	return
 }
 
+// LookupItemByName returns the item with the given name in the given version.
 func LookupItemByName(version string, name string) (item *Item, ok bool) {
 	for _, i := range ItemsForVersion(version) {
 		if i.Name == name {

mc/data/protocol_version.go

@@ -20,6 +20,7 @@ type VersionInfo struct {
 
 var ProtocolVersions []VersionInfo
 
+// LookUpVersionByName returns the VersionInfo for the given Minecraft version name (e.g. "1.21.11").
 func LookUpVersionByName(name string) (ret VersionInfo, err error) {
 	for _, v := range ProtocolVersions {
 		if v.MinecraftVersion == name {
@@ -31,6 +32,7 @@ func LookUpVersionByName(name string) (ret VersionInfo, err error) {
 	return
 }
 
+// LookUpVersionByProtocolVersion returns the VersionInfo for the given protocol version number.
 func LookUpVersionByProtocolVersion(version int32) (ret VersionInfo, err error) {
 	for _, v := range ProtocolVersions {
 		if v.Version == version {
@@ -42,6 +44,7 @@ func LookUpVersionByProtocolVersion(version int32) (ret VersionInfo, err error)
 	return
 }
 
+// LookUpVersionByDataVersion returns the VersionInfo for the given Minecraft data version number.
 func LookUpVersionByDataVersion(version int32) (ret VersionInfo, err error) {
 	for _, v := range ProtocolVersions {
 		if v.DataVersion == version {

mc/data/registry.go

@@ -11,6 +11,7 @@ import (
 //go:embed registry/*
 var Registry embed.FS
 
+// LoadRegistry loads a registry NBT file by name from the embedded registry data.
 func LoadRegistry(name string) (n *nbt2.Tag, err error) {
 	r, err := Registry.Open("registry/" + name + ".nbt")
 	if err != nil {