docs: add godoc comments to all exported functions and methods

mc/api/unauthenticated.go

@@ -9,6 +9,8 @@ import (
 	"strings"
 )
 
+// BlockedServers fetches the list of SHA-1 hashes of blocked server IPs from
+// Mojang's session server. The returned strings are hex-encoded hashes.
 func BlockedServers() (s []string, err error) {
 	resp, err := http.Get("https://sessionserver.mojang.com/blockedservers")
 	if err != nil {
@@ -36,6 +38,9 @@ type ProfileResp struct {
 	Properties []ProfileProperty `json:"properties"`
 }
 
+// HasJoined checks with Mojang's session server whether a player has joined a
+// given server. name is the player name, server is the server hash, and ip is
+// the optional player IP address. Returns the player's profile on success.
 func HasJoined(name, server, ip string) (p ProfileResp, err error) {
 	url := "https://sessionserver.mojang.com/session/minecraft/hasJoined?username=" + name + "&serverId=" + server
 	if ip != "" {
@@ -62,6 +67,8 @@ type MojangPublicKeysResp struct {
 	AuthenticationKeys []string `json:"authenticationKeys"`
 }
 
+// MojangPublicKeys fetches Mojang's public keys for profile property signing and
+// player certificate verification from the session server.
 func MojangPublicKeys() (keys MojangPublicKeysResp, err error) {
 	resp, err := http.Get("https://sessionserver.mojang.com/session/minecraft/profile/public_key_by_token")
 	if err != nil {
@@ -72,6 +79,8 @@ func MojangPublicKeys() (keys MojangPublicKeysResp, err error) {
 	return
 }
 
+// Profile fetches a player's profile by UUID from Mojang's session server.
+// If unsigned is false, signed profile properties are included in the response.
 func Profile(id string, unsinged bool) (p ProfileResp, err error) {
 	url := "https://sessionserver.mojang.com/session/minecraft/profile/" + id
 	if !unsinged {
@@ -91,6 +100,8 @@ type IdName struct {
 	Name string `json:"name"`
 }
 
+// NameToId resolves a Minecraft player name to a UUID and canonical name by
+// making an HTTP GET to Mojang's API.
 func NameToId(name string) (idName IdName, err error) {
 	// may also use these:
 	//https://api.mojang.com/users/profiles/minecraft/<player name>
@@ -105,6 +116,8 @@ func NameToId(name string) (idName IdName, err error) {
 	return
 }
 
+// NameToIdBulk resolves multiple Minecraft player names to UUIDs and canonical
+// names in a single HTTP POST to Mojang's API.
 func NameToIdBulk(names []string) (idNames []IdName, err error) {
 	b := bytes.NewBuffer(nil)
 	err = json.NewEncoder(b).Encode(names)