Fix function comments based on best practices from Effective Go

cmd/grumble/channel.go

@@ -41,38 +41,38 @@ func NewChannel(id int, name string) (channel *Channel) {
 	return
 }
 
-// Add a child channel to a channel
+// AddChild adds a child channel to a channel
 func (channel *Channel) AddChild(child *Channel) {
 	child.parent = channel
 	child.ACL.Parent = &channel.ACL
 	channel.children[child.Id] = child
 }
 
-// Remove a child channel from a parent
+// RemoveChild removes a child channel from a parent
 func (channel *Channel) RemoveChild(child *Channel) {
 	child.parent = nil
 	child.ACL.Parent = nil
 	delete(channel.children, child.Id)
 }
 
-// Add client
+// AddClient adds client
 func (channel *Channel) AddClient(client *Client) {
 	channel.clients[client.Session()] = client
 	client.Channel = channel
 }
 
-// Remove client
+// RemoveClient removes client
 func (channel *Channel) RemoveClient(client *Client) {
 	delete(channel.clients, client.Session())
 	client.Channel = nil
 }
 
-// Does the channel have a description?
+// HasDescription Does the channel have a description?
 func (channel *Channel) HasDescription() bool {
 	return len(channel.DescriptionBlob) > 0
 }
 
-// Get the channel's blob hash as a byte slice for sending via a protobuf message.
+// DescriptionBlobHashBytes gets the channel's blob hash as a byte slice for sending via a protobuf message.
 // Returns nil if there is no blob.
 func (channel *Channel) DescriptionBlobHashBytes() (buf []byte) {
 	buf, err := hex.DecodeString(channel.DescriptionBlob)
@@ -82,7 +82,7 @@ func (channel *Channel) DescriptionBlobHashBytes() (buf []byte) {
 	return buf
 }
 
-// Returns a slice of all channels in this channel's
+// AllLinks returns a slice of all channels in this channel's
 // link chain.
 func (channel *Channel) AllLinks() (seen map[int]*Channel) {
 	seen = make(map[int]*Channel)
@@ -100,7 +100,7 @@ func (channel *Channel) AllLinks() (seen map[int]*Channel) {
 	return
 }
 
-// Returns a slice of all of this channel's subchannels.
+// AllSubChannels returns a slice of all of this channel's subchannels.
 func (channel *Channel) AllSubChannels() (seen map[int]*Channel) {
 	seen = make(map[int]*Channel)
 	walk := []*Channel{}
@@ -120,12 +120,12 @@ func (channel *Channel) AllSubChannels() (seen map[int]*Channel) {
 	return
 }
 
-// Checks whether the channel is temporary
+// IsTemporary checks whether the channel is temporary
 func (channel *Channel) IsTemporary() bool {
 	return channel.temporary
 }
 
-// Checks whether the channel is temporary
+// IsEmpty checks whether the channel is temporary
 func (channel *Channel) IsEmpty() bool {
 	return len(channel.clients) == 0
 }

cmd/grumble/client.go

@@ -96,17 +96,17 @@ func (client *Client) Debugf(format string, v ...interface{}) {
 	client.Printf(format, v...)
 }
 
-// Is the client a registered user?
+// IsRegistered Is the client a registered user?
 func (client *Client) IsRegistered() bool {
 	return client.user != nil
 }
 
-// Does the client have a certificate?
+// HasCertificate Does the client have a certificate?
 func (client *Client) HasCertificate() bool {
 	return len(client.certHash) > 0
 }
 
-// Is the client the SuperUser?
+// IsSuperUser Is the client the SuperUser?
 func (client *Client) IsSuperUser() bool {
 	if client.user == nil {
 		return false
@@ -130,7 +130,7 @@ func (client *Client) Tokens() []string {
 	return client.tokens
 }
 
-// Get the User ID of this client.
+// UserId gets the User ID of this client.
 // Returns -1 if the client is not a registered user.
 func (client *Client) UserId() int {
 	if client.user == nil {
@@ -139,7 +139,7 @@ func (client *Client) UserId() int {
 	return int(client.user.Id)
 }
 
-// Get the client's shown name.
+// ShownName gets the client's shown name.
 func (client *Client) ShownName() string {
 	if client.IsSuperUser() {
 		return "SuperUser"
@@ -150,7 +150,7 @@ func (client *Client) ShownName() string {
 	return client.Username
 }
 
-// Check whether the client's certificate is
+// IsVerified checks whether the client's certificate is
 // verified.
 func (client *Client) IsVerified() bool {
 	tlsconn := client.conn.(*tls.Conn)
@@ -207,7 +207,7 @@ func (client *Client) ForceDisconnect() {
 	client.disconnect(true)
 }
 
-// Clear the client's caches
+// ClearCaches clears the client's caches
 func (client *Client) ClearCaches() {
 	for _, vt := range client.voiceTargets {
 		vt.ClearCache()

cmd/grumble/freeze.go

@@ -776,7 +776,7 @@ func (server *Server) UpdateFrozenChannel(channel *Channel, state *mumbleproto.C
 	server.numLogOps += 1
 }
 
-// Write a channel's ACL and Group data to disk. Mumble doesn't support
+// UpdateFrozenChannelACLs writes a channel's ACL and Group data to disk. Mumble doesn't support
 // incremental ACL updates and as such we must write all ACLs and groups
 // to the datastore on each change.
 func (server *Server) UpdateFrozenChannelACLs(channel *Channel) {
@@ -821,7 +821,7 @@ func (server *Server) DeleteFrozenChannel(channel *Channel) {
 	server.numLogOps += 1
 }
 
-// Write the server's banlist to the datastore.
+// UpdateFrozenBans writes the server's banlist to the datastore.
 func (server *Server) UpdateFrozenBans(bans []ban.Ban) {
 	fbl := &freezer.BanList{}
 	for _, ban := range server.Bans {
@@ -834,7 +834,7 @@ func (server *Server) UpdateFrozenBans(bans []ban.Ban) {
 	server.numLogOps += 1
 }
 
-// Write an updated config value to the datastore.
+// UpdateConfig writes an updated config value to the datastore.
 func (server *Server) UpdateConfig(key, value string) {
 	fcfg := &freezer.ConfigKeyValuePair{
 		Key:   proto.String(key),
@@ -847,7 +847,7 @@ func (server *Server) UpdateConfig(key, value string) {
 	server.numLogOps += 1
 }
 
-// Write to the freezelog that the config with key
+// ResetConfig writes to the freezelog that the config with key
 // has been reset to its default value.
 func (server *Server) ResetConfig(key string) {
 	fcfg := &freezer.ConfigKeyValuePair{

cmd/grumble/server.go

@@ -165,7 +165,7 @@ func (server *Server) Debugf(format string, v ...interface{}) {
 	server.Printf(format, v...)
 }
 
-// Get a pointer to the root channel
+// RootChannel gets a pointer to the root channel
 func (server *Server) RootChannel() *Channel {
 	root, exists := server.Channels[0]
 	if !exists {
@@ -195,7 +195,7 @@ func (server *Server) SetSuperUserPassword(password string) {
 	server.cfgUpdate <- &KeyValuePair{Key: key, Value: val}
 }
 
-// Check whether password matches the set SuperUser password.
+// CheckSuperUserPassword checks whether password matches the set SuperUser password.
 func (server *Server) CheckSuperUserPassword(password string) bool {
 	parts := strings.Split(server.cfg.StringValue("SuperUserPassword"), "$")
 	if len(parts) != 3 {
@@ -296,7 +296,7 @@ func (server *Server) handleIncomingClient(conn net.Conn) (err error) {
 	return
 }
 
-// Remove a disconnected client from the server's
+// RemoveClient removes a disconnected client from the server's
 // internal representation.
 func (server *Server) RemoveClient(client *Client, kicked bool) {
 	server.hmutex.Lock()
@@ -336,7 +336,7 @@ func (server *Server) RemoveClient(client *Client, kicked bool) {
 	}
 }
 
-// Add a new channel to the server. Automatically assign it a channel ID.
+// AddChannel adds a new channel to the server. Automatically assign it a channel ID.
 func (server *Server) AddChannel(name string) (channel *Channel) {
 	channel = NewChannel(server.nextChanId, name)
 	server.Channels[channel.Id] = channel
@@ -345,7 +345,7 @@ func (server *Server) AddChannel(name string) (channel *Channel) {
 	return
 }
 
-// Remove a channel from the server.
+// RemoveChanel removes a channel from the server.
 func (server *Server) RemoveChanel(channel *Channel) {
 	if channel.Id == 0 {
 		server.Printf("Attempted to remove root channel.")
@@ -1047,7 +1047,7 @@ func (server *Server) handleUdpPacket(udpaddr *net.UDPAddr, buf []byte) {
 	match.udprecv <- plain
 }
 
-// Clear the Server's caches
+// ClearCaches clears the Server's caches
 func (server *Server) ClearCaches() {
 	for _, client := range server.clients {
 		client.ClearCaches()
@@ -1115,7 +1115,7 @@ func (s *Server) RegisterClient(client *Client) (uid uint32, err error) {
 	return uid, nil
 }
 
-// Remove a registered user.
+// RemoveRegistration removes a registered user.
 func (s *Server) RemoveRegistration(uid uint32) (err error) {
 	user, ok := s.Users[uid]
 	if !ok {
@@ -1162,7 +1162,7 @@ func (s *Server) removeRegisteredUserFromChannel(uid uint32, channel *Channel) {
 	}
 }
 
-// Remove a channel
+// RemoveChannel removes a channel
 func (server *Server) RemoveChannel(channel *Channel) {
 	// Can't remove root
 	if channel == server.RootChannel() {
@@ -1207,7 +1207,7 @@ func (server *Server) RemoveChannel(channel *Channel) {
 	}
 }
 
-// Remove expired bans
+// RemoveExpiredBans removes expired bans
 func (server *Server) RemoveExpiredBans() {
 	server.banlock.Lock()
 	defer server.banlock.Unlock()
@@ -1228,7 +1228,7 @@ func (server *Server) RemoveExpiredBans() {
 	}
 }
 
-// Is the incoming connection conn banned?
+// IsConnectionBanned Is the incoming connection conn banned?
 func (server *Server) IsConnectionBanned(conn net.Conn) bool {
 	server.banlock.RLock()
 	defer server.banlock.RUnlock()
@@ -1243,7 +1243,7 @@ func (server *Server) IsConnectionBanned(conn net.Conn) bool {
 	return false
 }
 
-// Is the certificate hash banned?
+// IsCertHashBanned Is the certificate hash banned?
 func (server *Server) IsCertHashBanned(hash string) bool {
 	server.banlock.RLock()
 	defer server.banlock.RUnlock()
@@ -1344,7 +1344,7 @@ func (server *Server) cleanPerLaunchData() {
 	server.clientAuthenticated = nil
 }
 
-// Returns the port the native server will listen on when it is
+// Port returns the port the native server will listen on when it is
 // started.
 func (server *Server) Port() int {
 	port := server.cfg.IntValue("Port")
@@ -1354,7 +1354,7 @@ func (server *Server) Port() int {
 	return port
 }
 
-// Returns the port the web server will listen on when it is
+// WebPort returns the port the web server will listen on when it is
 // started.
 func (server *Server) WebPort() int {
 	port := server.cfg.IntValue("WebPort")
@@ -1364,7 +1364,7 @@ func (server *Server) WebPort() int {
 	return port
 }
 
-// Returns the port the native server is currently listening
+// CurrentPort returns the port the native server is currently listening
 // on.  If called when the server is not running,
 // this function returns -1.
 func (server *Server) CurrentPort() int {
@@ -1375,7 +1375,7 @@ func (server *Server) CurrentPort() int {
 	return tcpaddr.Port
 }
 
-// Returns the host address the server will listen on when
+// HostAddress returns the host address the server will listen on when
 // it is started. This must be an IP address, either IPv4
 // or IPv6.
 func (server *Server) HostAddress() string {

cmd/grumble/user.go

@@ -40,12 +40,12 @@ func NewUser(id uint32, name string) (user *User, err error) {
 	}, nil
 }
 
-// Does the channel have comment?
+// HasComment Does the channel have comment?
 func (user *User) HasComment() bool {
 	return len(user.CommentBlob) > 0
 }
 
-// Get the hash of the user's comment blob as a byte slice for transmitting via a protobuf message.
+// CommentBlobHashBytes gets the hash of the user's comment blob as a byte slice for transmitting via a protobuf message.
 // Returns nil if there is no such blob.
 func (user *User) CommentBlobHashBytes() (buf []byte) {
 	buf, err := hex.DecodeString(user.CommentBlob)
@@ -55,12 +55,12 @@ func (user *User) CommentBlobHashBytes() (buf []byte) {
 	return buf
 }
 
-// Does the user have a texture?
+// HasTexture Does the user have a texture?
 func (user *User) HasTexture() bool {
 	return len(user.TextureBlob) > 0
 }
 
-// Get the hash of the user's texture blob as a byte slice for transmitting via a protobuf message.
+// TextureBlobHashBytes gets the hash of the user's texture blob as a byte slice for transmitting via a protobuf message.
 // Returns nil if there is no such blob.
 func (user *User) TextureBlobHashBytes() (buf []byte) {
 	buf, err := hex.DecodeString(user.TextureBlob)

cmd/grumble/voicetarget.go

@@ -28,7 +28,7 @@ func (vt *VoiceTarget) AddSession(session uint32) {
 	vt.sessions = append(vt.sessions, session)
 }
 
-// Add a channel to the VoiceTarget.
+// AddChannel adds a channel to the VoiceTarget.
 // If subchannels is true, any sent voice packets will also be sent to all subchannels.
 // If links is true, any sent voice packets will also be sent to all linked channels.
 // If group is a non-empty string, any sent voice packets will only be broadcast to members
@@ -42,12 +42,12 @@ func (vt *VoiceTarget) AddChannel(id uint32, subchannels bool, links bool, group
 	})
 }
 
-// Checks whether the VoiceTarget is empty (has no targets)
+// IsEmpty checks whether the VoiceTarget is empty (has no targets)
 func (vt *VoiceTarget) IsEmpty() bool {
 	return len(vt.sessions) == 0 && len(vt.channels) == 0
 }
 
-// Clear the VoiceTarget's cache.
+// ClearCache clears the VoiceTarget's cache.
 func (vt *VoiceTarget) ClearCache() {
 	vt.directCache = nil
 	vt.fromChannelsCache = nil

pkg/acl/group.go

@@ -336,7 +336,7 @@ func GroupMemberCheck(current *Context, acl *Context, name string, user User) (o
 	return false
 }
 
-// Get the list of group names for the given ACL context.
+// GroupNames gets the list of group names for the given ACL context.
 //
 // This function walks the through the context chain to figure
 // out all groups that affect the given context whilst considering

pkg/ban/ban.go

@@ -41,7 +41,7 @@ func (ban Ban) IPMask() (mask net.IPMask) {
 	return
 }
 
-// Check whether an IP matches a Ban
+// Match checks whether an IP matches a Ban
 func (ban Ban) Match(ip net.IP) bool {
 	banned := ban.IP.Mask(ban.IPMask())
 	masked := ip.Mask(ban.IPMask())
@@ -58,14 +58,14 @@ func (ban *Ban) SetISOStartDate(isodate string) {
 	}
 }
 
-// Return the currently set start date as an ISO 8601-formatted
+// ISOStartDate returns the currently set start date as an ISO 8601-formatted
 // date (in UTC).
 func (ban Ban) ISOStartDate() string {
 	startTime := time.Unix(ban.Start, 0).UTC()
 	return startTime.Format(ISODate)
 }
 
-// Check whether a ban has expired
+// IsExpired checks whether a ban has expired
 func (ban Ban) IsExpired() bool {
 	// ∞-case
 	if ban.Duration == 0 {