Participants: document that returned slices are snapshots (fixes #100)

Author: markus-wa

game_state.go

@@ -143,7 +143,7 @@ type Participants struct {
 }
 
 // ByUserID returns all currently connected players in a map where the key is the user-ID.
-// The map is a snapshot and is not updated (not a reference to the actual, underlying map).
+// The returned map is a snapshot and is not updated on changes (not a reference to the actual, underlying map).
 // Includes spectators.
 func (ptcp Participants) ByUserID() map[int]*common.Player {
 	res := make(map[int]*common.Player)
@@ -154,7 +154,7 @@ func (ptcp Participants) ByUserID() map[int]*common.Player {
 }
 
 // ByEntityID returns all currently connected players in a map where the key is the entity-ID.
-// The map is a snapshot and is not updated (not a reference to the actual, underlying map).
+// The returned map is a snapshot and is not updated on changes (not a reference to the actual, underlying map).
 // Includes spectators.
 func (ptcp Participants) ByEntityID() map[int]*common.Player {
 	res := make(map[int]*common.Player)
@@ -165,6 +165,7 @@ func (ptcp Participants) ByEntityID() map[int]*common.Player {
 }
 
 // All returns all currently connected players & spectators.
+// The returned slice is a snapshot and is not updated on changes.
 func (ptcp Participants) All() []*common.Player {
 	res := make([]*common.Player, 0, len(ptcp.playersByUserID))
 	for _, p := range ptcp.playersByUserID {
@@ -174,6 +175,7 @@ func (ptcp Participants) All() []*common.Player {
 }
 
 // Playing returns all players that aren't spectating or unassigned.
+// The returned slice is a snapshot and is not updated on changes.
 func (ptcp Participants) Playing() []*common.Player {
 	res := make([]*common.Player, 0, len(ptcp.playersByUserID))
 	for _, p := range ptcp.playersByUserID {
@@ -185,6 +187,7 @@ func (ptcp Participants) Playing() []*common.Player {
 }
 
 // TeamMembers returns all players belonging to the requested team at this time.
+// The returned slice is a snapshot and is not updated on changes.
 func (ptcp Participants) TeamMembers(team common.Team) []*common.Player {
 	res := make([]*common.Player, 0, len(ptcp.playersByUserID))
 	for _, ptcp := range ptcp.playersByUserID {

participants_interface.go

@@ -13,18 +13,21 @@ import (
 // See GameState.Participants()
 type IParticipants interface {
 	// ByUserID returns all currently connected players in a map where the key is the user-ID.
-	// The map is a snapshot and is not updated (not a reference to the actual, underlying map).
+	// The returned map is a snapshot and is not updated on changes (not a reference to the actual, underlying map).
 	// Includes spectators.
 	ByUserID() map[int]*common.Player
 	// ByEntityID returns all currently connected players in a map where the key is the entity-ID.
-	// The map is a snapshot and is not updated (not a reference to the actual, underlying map).
+	// The returned map is a snapshot and is not updated on changes (not a reference to the actual, underlying map).
 	// Includes spectators.
 	ByEntityID() map[int]*common.Player
 	// All returns all currently connected players & spectators.
+	// The returned slice is a snapshot and is not updated on changes.
 	All() []*common.Player
 	// Playing returns all players that aren't spectating or unassigned.
+	// The returned slice is a snapshot and is not updated on changes.
 	Playing() []*common.Player
 	// TeamMembers returns all players belonging to the requested team at this time.
+	// The returned slice is a snapshot and is not updated on changes.
 	TeamMembers(team common.Team) []*common.Player
 	// FindByHandle attempts to find a player by his entity-handle.
 	// The entity-handle is often used in entity-properties when referencing other entities such as a weapon's owner.