Improve godoc

Author: markus-wa

bitread/bitread.go

@@ -1,4 +1,6 @@
 // Package bitread provides a wrapper for github.com/markus-wa/gobitread with CS:GO demo parsing specific helpers.
+//
+// Intended for internal use only.
 package bitread
 
 import (

common/constants.go

@@ -151,13 +151,14 @@ func (e EquipmentElement) Class() EquipmentClass {
 }
 
 // String returns a human readable name for the equipment.
-// E.g. AK-47, UMP-45, Smoke Grenade etc.
+// E.g. 'AK-47', 'UMP-45', 'Smoke Grenade' etc.
 func (e EquipmentElement) String() string {
 	return eqElementToName[e]
 }
 
 // EquipmentClass constants give information about the type of an equipment (SMG, Rifle, Grenade etc.).
-// Note: EquipmentElement / 100 = EquipmentClass
+//
+// Note: (EquipmentElement+99) / 100 = EquipmentClass
 const (
 	EqClassUnknown   EquipmentClass = 0
 	EqClassPistols   EquipmentClass = 1

common/structs.go

@@ -8,7 +8,7 @@ import (
 	st "github.com/markus-wa/demoinfocs-golang/sendtables"
 )
 
-// DemoHeader contains information about the demo's header.
+// DemoHeader contains information from a demo's header.
 type DemoHeader struct {
 	Filestamp       string
 	Protocol        int
@@ -76,7 +76,7 @@ func (p *Player) ActiveWeapon() *Equipment {
 	return p.RawWeapons[p.ActiveWeaponID]
 }
 
-// Weapons returns all weapons in the player's possession
+// Weapons returns all weapons in the player's possession.
 func (p *Player) Weapons() []*Equipment {
 	res := make([]*Equipment, 0, len(p.RawWeapons))
 	for _, w := range p.RawWeapons {
@@ -140,6 +140,8 @@ func (e Equipment) UniqueID() int64 {
 }
 
 // NewGrenadeProjectile creates a grenade projectile and sets.
+//
+// Intended for internal use only.
 func NewGrenadeProjectile() *GrenadeProjectile {
 	return &GrenadeProjectile{uniqueID: rand.Int63()}
 }
@@ -152,11 +154,15 @@ func (g GrenadeProjectile) UniqueID() int64 {
 }
 
 // NewEquipment is a wrapper for NewSkinEquipment to create weapons without skins.
+//
+// Intended for internal use only.
 func NewEquipment(eqName string) Equipment {
 	return NewSkinEquipment(eqName, "")
 }
 
 // NewSkinEquipment creates an equipment with a skin from a skinID and equipment name.
+//
+// Intended for internal use only.
 func NewSkinEquipment(eqName string, skinID string) Equipment {
 	var wep EquipmentElement
 	if len(eqName) > 0 {
@@ -168,6 +174,8 @@ func NewSkinEquipment(eqName string, skinID string) Equipment {
 }
 
 // NewPlayer creates a *Player with an initialized equipment map.
+//
+// Intended for internal use only.
 func NewPlayer() *Player {
 	return &Player{RawWeapons: make(map[int]*Equipment)}
 }

demopacket.go

@@ -10,6 +10,11 @@ import (
 	msg "github.com/markus-wa/demoinfocs-golang/msg"
 )
 
+// NetMessageCreator creates additional net-messages to be dispatched to net-message handlers.
+//
+// See also: ParserConfig.AdditionalNetMessageCreators & Parser.RegisterNetMessageHandler()
+type NetMessageCreator func() proto.Message
+
 var byteSlicePool = sync.Pool{
 	New: func() interface{} {
 		s := make([]byte, 0, 256)
@@ -101,10 +106,6 @@ func (p *Parser) parsePacket() {
 	p.bitReader.EndChunk()
 }
 
-// NetMessageCreator creates additional net-messages to be dispatched to net-message handlers.
-// See also: ParserConfig.AdditionalNetMessageCreators & Parser.RegisterNetMessageHandler()
-type NetMessageCreator func() proto.Message
-
 /*
 Format of 'CommandInfos' - I honestly have no clue what they are good for.
 If you find a use for this please let me know!

doc.go

@@ -1,5 +1,9 @@
-// Package demoinfocs provides a demo parser for the game Counter-Strike: Global Offensive.
-// It is based on the official demoinfogo tool by Valve as well as Stats Helix's demoinfo.
-// A good entry point to using the library is the Parser type.
-// Demo events are documented in the events package.
+/*
+Package demoinfocs provides a demo parser for the game Counter-Strike: Global Offensive.
+It is based on the official demoinfogo tool by Valve as well as Stats Helix's demoinfo.
+
+A good entry point to using the library is the Parser type.
+
+Demo events are documented in the events package.
+*/
 package demoinfocs

events/events.go

@@ -60,7 +60,7 @@ type LastRoundHalfEvent struct{}
 // FreezetimeEndedEvent signals that the freeze time is over.
 type FreezetimeEndedEvent struct{}
 
-// PlayerFootstepEvent occurs when a player makes a footstep
+// PlayerFootstepEvent occurs when a player makes a footstep.
 type PlayerFootstepEvent struct {
 	Player *common.Player
 }
@@ -118,7 +118,7 @@ type NadeEvent struct {
 	NadeEntityID int
 }
 
-// Base returns the NadeEvent itself, used for catching all events with NadeEventIf
+// Base returns the NadeEvent itself, used for catching all events with NadeEventIf.
 func (ne NadeEvent) Base() NadeEvent {
 	return ne
 }
@@ -164,7 +164,7 @@ type FireNadeEndEvent struct {
 	NadeEvent
 }
 
-// NadeProjectileBouncedEvent signals that a nade has just bounced off a wall/floor/ceiling or object
+// NadeProjectileBouncedEvent signals that a nade has just bounced off a wall/floor/ceiling or object.
 type NadeProjectileBouncedEvent struct {
 	Projectile *common.GrenadeProjectile
 	BounceNr   int
@@ -297,7 +297,7 @@ type RankUpdateEvent struct {
 	RankChange float32
 }
 
-// ItemEquipEvent signals an item was equipped
+// ItemEquipEvent signals an item was equipped.
 type ItemEquipEvent struct {
 	Weapon common.Equipment
 	Player *common.Player
@@ -309,7 +309,7 @@ type ItemPickupEvent struct {
 	Player *common.Player
 }
 
-// ItemDropEvent signals an item was dropped
+// ItemDropEvent signals an item was dropped.
 type ItemDropEvent struct {
 	Weapon common.Equipment
 	Player *common.Player

fuzzy/team_switch.go

@@ -8,12 +8,15 @@ import (
 )
 
 // TeamSwitchEvent signals that the teams have switched.
+//
 // See also: ValveMatchmakingTeamSwitchEmitter
 type TeamSwitchEvent struct{}
 
 // ValveMatchmakingTeamSwitchEmitter emits a TeamSwitchEvent for Valve MM demos.
 // Sadly this WON'T work for Major games as it currently doesn't account for overtime.
+//
 // This is a beta feature and may be changed or replaced without notice.
+//
 // See also: github.com/markus-wa/demoinfocs-golang/ParserConfig.AdditionalEventEmitters
 type ValveMatchmakingTeamSwitchEmitter struct {
 	parser              *dem.Parser

game_state.go

@@ -21,19 +21,22 @@ func (gs *GameState) handleIngameTickNumber(n ingameTickNumber) {
 }
 
 // IngameTick returns the latest actual tick number of the server during the game.
+//
 // Watch out, I've seen this return wonky negative numbers at the start of demos.
 func (gs GameState) IngameTick() int {
 	return gs.ingameTick
 }
 
 // CTState returns the TeamState of the CT team.
-// Make sure you handle swapping sides properly if you keep the reference.
+//
+// Make sure to handle swapping sides properly if you keep the reference.
 func (gs *GameState) CTState() *TeamState {
 	return &gs.ctState
 }
 
 // TState returns the TeamState of the T team.
-// Make sure you handle swapping sides properly if you keep the reference.
+//
+// Make sure to handle swapping sides properly if you keep the reference.
 func (gs *GameState) TState() *TeamState {
 	return &gs.tState
 }
@@ -70,8 +73,10 @@ func (gs GameState) TeamMembers(team common.Team) []*common.Player {
 	return r
 }
 
-// GrenadeProjectiles returns a map with all grenade projectiles. The map contains only projectiles
-// that are currently in-flight, i.e. have been thrown but have yet to detonate.
+// GrenadeProjectiles returns a map from entity-IDs to all live grenade projectiles.
+//
+// Only constains projectiles currently in-flight or still active (smokes etc.),
+// i.e. have been thrown but have yet to detonate.
 func (gs GameState) GrenadeProjectiles() map[int]*common.GrenadeProjectile {
 	return gs.grenadeProjectiles
 }
@@ -92,6 +97,7 @@ type TeamState struct {
 }
 
 // ID returns the team-ID.
+//
 // This stays the same even after switching sides.
 func (ts TeamState) ID() int {
 	return ts.id
@@ -108,6 +114,7 @@ func (ts TeamState) ClanName() string {
 }
 
 // Flag returns the team's country flag.
+//
 // Watch out, in some demos this is upper-case and in some lower-case.
 func (ts TeamState) Flag() string {
 	return ts.flag

msg/msg.go

@@ -1,4 +1,5 @@
 // Package msg contains the generated protobuf demo message code.
+//
 // Use 'go generate' to generate the code from the .proto files inside the proto sub directory.
 package msg