add docs to auth, buddy, chat, icbm, oservice handlers

handler/auth.go

@@ -75,13 +75,12 @@ func (s AuthService) SignoutChat(ctx context.Context, sess *state.Session, chatI
 }
 
 // BUCPChallengeRequestHandler satisfies the client request for a random auth
-// key. It returns SNAC oscar.BUCPChallengeResponse. If the screen name in
-// TLV oscar.TLVScreenName in bodyIn is recognized as a valid user, the
-// response contains the account's auth key, which salt's the user's MD5
-// password hash. If the account is invalid, an error code is set in TLV
-// oscar.TLVErrorSubcode. If login credentials are invalid and app config
-// DisableAuth is true, a stub auth key is generated and a successful challenge
-// response is returned.
+// key. It returns SNAC oscar.BUCPChallengeResponse. If the screen name is
+// recognized as a valid user, the response contains the account's auth key,
+// which salts the user's MD5 password hash. If the account is invalid, an
+// error code is set in TLV oscar.TLVErrorSubcode. If login credentials are
+// invalid and app config DisableAuth is true, a stub auth key is generated and
+// a successful challenge response is returned.
 func (s AuthService) BUCPChallengeRequestHandler(bodyIn oscar.SNAC_0x17_0x06_BUCPChallengeRequest, newUUIDFn func() uuid.UUID) (oscar.SNACMessage, error) {
 	screenName, exists := bodyIn.String(oscar.TLVScreenName)
 	if !exists {

handler/buddy.go

@@ -7,13 +7,20 @@ import (
 	"github.com/mk6i/retro-aim-server/state"
 )
 
+// NewBuddyService creates a new instance of BuddyService.
 func NewBuddyService() *BuddyService {
 	return &BuddyService{}
 }
 
+// BuddyService provides functionality for the buddy food group, which sends
+// clients notifications about the state of users on their buddy list. The food
+// group is used by old versions of AIM not currently supported by Retro Aim
+// Server. BuddyService just exists to satisfy AIM 5.x's buddy rights requests.
+// It may be expanded in the future to support older versions of AIM.
 type BuddyService struct {
 }
 
+// RightsQueryHandler returns buddy list service parameters.
 func (s BuddyService) RightsQueryHandler(_ context.Context, frameIn oscar.SNACFrame) oscar.SNACMessage {
 	return oscar.SNACMessage{
 		Frame: oscar.SNACFrame{

handler/chat.go

@@ -7,16 +7,22 @@ import (
 	"github.com/mk6i/retro-aim-server/state"
 )
 
+// NewChatService creates a new instance of ChatService.
 func NewChatService(chatRegistry ChatRegistry) *ChatService {
 	return &ChatService{
 		chatRegistry: chatRegistry,
 	}
 }
 
+// ChatService implements chat message handling for the chat food group.
 type ChatService struct {
 	chatRegistry ChatRegistry
 }
 
+// ChannelMsgToHostHandler relays oscar.ChatChannelMsgToClient SNAC sent from a
+// user to the other chat room participants. It returns the same
+// oscar.ChatChannelMsgToClient message back to the user if the chat reflection
+// TLV flag is set, otherwise return nil.
 func (s ChatService) ChannelMsgToHostHandler(ctx context.Context, sess *state.Session, chatID string, inFrame oscar.SNACFrame, inBody oscar.SNAC_0x0E_0x05_ChatChannelMsgToHost) (*oscar.SNACMessage, error) {
 	frameOut := oscar.SNACFrame{
 		FoodGroup: oscar.Chat,

handler/icbm.go

@@ -12,15 +12,20 @@ const (
 	evilDeltaAnon = uint16(30)
 )
 
+// NewICBMService returns a new instance of ICBMService.
 func NewICBMService(messageRelayer MessageRelayer, feedbagManager FeedbagManager) *ICBMService {
 	return &ICBMService{messageRelayer: messageRelayer, feedbagManager: feedbagManager}
 }
 
+// ICBMService implements the ICBM food group, which is responsible for sending
+// and receiving instant messages and associated functionality such as warning,
+// typing events, etc.
 type ICBMService struct {
 	messageRelayer MessageRelayer
 	feedbagManager FeedbagManager
 }
 
+// ParameterQueryHandler returns ICBM service parameters.
 func (s ICBMService) ParameterQueryHandler(_ context.Context, inFrame oscar.SNACFrame) oscar.SNACMessage {
 	return oscar.SNACMessage{
 		Frame: oscar.SNACFrame{
@@ -39,6 +44,10 @@ func (s ICBMService) ParameterQueryHandler(_ context.Context, inFrame oscar.SNAC
 	}
 }
 
+// ChannelMsgToHostHandler relays the instant message SNAC
+// oscar.ICBMChannelMsgToHost from the sender to the intended recipient. It
+// returns oscar.ICBMHostAck if the oscar.ICBMChannelMsgToHost message contains
+// a request acknowledgement flag.
 func (s ICBMService) ChannelMsgToHostHandler(ctx context.Context, sess *state.Session, inFrame oscar.SNACFrame, inBody oscar.SNAC_0x04_0x06_ICBMChannelMsgToHost) (*oscar.SNACMessage, error) {
 	blocked, err := s.feedbagManager.BlockedState(sess.ScreenName(), inBody.ScreenName)
 	if err != nil {
@@ -125,6 +134,8 @@ func (s ICBMService) ChannelMsgToHostHandler(ctx context.Context, sess *state.Se
 	}, nil
 }
 
+// ClientEventHandler relays SNAC oscar.ICBMClientEvent typing events from the
+// sender to the recipient.
 func (s ICBMService) ClientEventHandler(ctx context.Context, sess *state.Session, inFrame oscar.SNACFrame, inBody oscar.SNAC_0x04_0x14_ICBMClientEvent) error {
 	blocked, err := s.feedbagManager.BlockedState(sess.ScreenName(), inBody.ScreenName)
 
@@ -151,6 +162,13 @@ func (s ICBMService) ClientEventHandler(ctx context.Context, sess *state.Session
 	}
 }
 
+// EvilRequestHandler handles user warning (a.k.a evil) notifications. It
+// receives oscar.ICBMEvilRequest warning SNAC, increments the warned user's
+// warning level, and sends the warned user a notification informing them that
+// they have been warned. The user may choose to warn anonymously or
+// non-anonymously. It returns SNAC oscar.ICBMEvilReply to confirm that the
+// warning was sent. Users may not warn themselves or warn users they have
+// blocked or are blocked by.
 func (s ICBMService) EvilRequestHandler(ctx context.Context, sess *state.Session, inFrame oscar.SNACFrame, inBody oscar.SNAC_0x04_0x08_ICBMEvilRequest) (oscar.SNACMessage, error) {
 	// don't let users warn themselves, it causes the AIM client to go into a
 	// weird state.
@@ -218,6 +236,7 @@ func (s ICBMService) EvilRequestHandler(ctx context.Context, sess *state.Session
 		Body: notif,
 	})
 
+	// inform the warned user's buddies that their warning level has increased
 	if err := broadcastArrival(ctx, recipSess, s.messageRelayer, s.feedbagManager); err != nil {
 		return oscar.SNACMessage{}, nil
 	}

handler/oservice.go

@@ -56,7 +56,7 @@ func (s OServiceService) ClientVersionsHandler(_ context.Context, frame oscar.SN
 // Instead, the provided values inform the client about the recommended
 // client-side rate limits.
 //
-// It returns SNAC osca.rOServiceRateParamsReply containing rate limits for
+// It returns SNAC oscar.OServiceRateParamsReply containing rate limits for
 // sending Instant Messages (IMs) and chat messages. More refined limits may be
 // added in the future if/when server rate limiting is implemented.
 func (s OServiceService) RateParamsQueryHandler(_ context.Context, inFrame oscar.SNACFrame) oscar.SNACMessage {