Update getAuthChain comments following @babolivier review

roomserver/query/query.go

@@ -609,36 +609,39 @@ func (r *RoomserverQueryAPI) QueryStateAndAuthChain(
 	return err
 }
 
-// getAuthChain fetches the auth chain for the given auth events.
+// getAuthChain fetches the auth chain for the given auth events. An auth chain
-// An auth chain is the list of all events that are referenced in the
+// is the list of all events that are referenced in the auth_events section, and
-// auth_events section, and all their auth_events, recursively.
+// all their auth_events, recursively. The returned set of events contain the
-// The returned set of events contain the given events.
+// given events. Will *not* error if we don't have all auth events.
-// Will *not* error if we don't have all auth events.
 func getAuthChain(
 	ctx context.Context, dB RoomserverQueryAPIEventDB, authEventIDs []string,
 ) ([]gomatrixserverlib.Event, error) {
+	// List of event IDs to fetch. On each pass, these events will be requested
+	// from the database and the `eventsToFetch` will be updated with any new
+	// events that we have learned about and need to find. When `eventsToFetch`
+	// is eventually empty, we should have reached the end of the chain.
 	eventsToFetch := authEventIDs
 	authEventsMap := make(map[string]gomatrixserverlib.Event)
 
 	for len(eventsToFetch) > 0 {
-		// Try to retrieve the events from the database
+		// Try to retrieve the events from the database.
 		events, err := dB.EventsFromIDs(ctx, eventsToFetch)
 		if err != nil {
 			return nil, err
 		}
 
-		// Clear out the events to fetch, since we have already requested them, and
+		// We've now fetched these events so clear out `eventsToFetch`. Soon we may
-		// we may now get new ones
+		// add newly discovered events to this for the next pass.
 		eventsToFetch = eventsToFetch[:0]
 
 		for _, event := range events {
 			// Store the event in the event map - this prevents us from requesting it
-			// again, and we'll return this later
+			// from the database again.
 			authEventsMap[event.EventID()] = event.Event
 
 			// Extract all of the auth events from the newly obtained event. If we
 			// don't already have a record of the event, record it in the list of
-			// events we want to request
+			// events we want to request for the next pass.
 			for _, authEvent := range event.AuthEvents() {
 				if _, ok := authEventsMap[authEvent.EventID]; !ok {
 					eventsToFetch = append(eventsToFetch, authEvent.EventID)
@@ -647,7 +650,8 @@ func getAuthChain(
 		}
 	}
 
-	// Flatten the event map down into an array
+	// We've now retrieved all of the events we can. Flatten them down into an
+	// array and return them.
 	var authEvents []gomatrixserverlib.Event
 	for _, event := range authEventsMap {
 		authEvents = append(authEvents, event)