rename parameters, add comments

service/history/workflow/mutable_state.go

@@ -145,7 +145,7 @@ type (
 		MaxSearchAttributeValueSize int
 	}
 
-	UpdateActivityCallback func(*persistencespb.ActivityInfo, MutableState)
+	ActivityUpdater func(*persistencespb.ActivityInfo, MutableState)
 
 	MutableState interface {
 		callbacks.CanGetNexusCompletion
@@ -360,7 +360,7 @@ type (
 			baseRunLowestCommonAncestorEventID int64,
 			baseRunLowestCommonAncestorEventVersion int64,
 		)
-		UpdateActivity(string, UpdateActivityCallback) error
+		UpdateActivity(string, ActivityUpdater) error
 		UpdateActivityTimerHeartbeat(int64, time.Time)
 		UpdateActivityProgress(ai *persistencespb.ActivityInfo, request *workflowservice.RecordActivityTaskHeartbeatRequest)
 		UpdateUserTimer(*persistencespb.TimerInfo) error

service/history/workflow/mutable_state_impl.go

@@ -4940,6 +4940,16 @@ func (ms *MutableStateImpl) updateActivityInfoForRetries(
 	})
 }
 
+/*
+UpdateActivity function updates the existing pending activity via the updater callback.
+To update an activity, we need to do the following steps:
+	* preserve the original size of the activity
+	* preserve the original state of the activity
+	* call the updater callback to update the activity
+	* calculate new size of the activity
+	* respond to the changes of the activity state (like changes to pause)
+*/
+
 func (ms *MutableStateImpl) UpdateActivity(activityId string, updater ActivityUpdater) error {
 	ai, activityFound := ms.GetActivityByActivityID(activityId)
 	if !activityFound {
@@ -4953,7 +4963,7 @@ func (ms *MutableStateImpl) UpdateActivity(activityId string, updater ActivityUp
 		prevPause = prev.Paused
 	}
 
-	updateCallback(ai, ms)
+	updater(ai, ms)
 
 	if prevPause != ai.Paused {
 		err := ms.updatePauseInfoSearchAttribute()