add comments to handleRequested and handleReserve

Patch for "plugin: Add transactions for speculative operations"

pkg/plugin/trans.go

@@ -66,6 +66,8 @@ func (s verdictSet) MarshalLogObject(enc zapcore.ObjectEncoder) error {
 
 // handleReserve adds the resources from the pod to the node, reporting if the node was over-budget
 //
+// Unlike handleRequested, this method should be called to add a NEW pod to the node.
+//
 // This is used in combination with Xact to speculatively *try* reserving a pod, and then revert if
 // it would result in being over-budget.
 func (r resourceTransitioner[T]) handleReserve() (overbudget bool, verdict string) {
@@ -133,6 +135,9 @@ func (r resourceTransitioner[T]) handleReserve() (overbudget bool, verdict strin
 //
 // Any permitted increases are required to be a multiple of factor.
 //
+// Unlike handleReserve, this method should be called to update the resources for a preexisting pod
+// on the node.
+//
 // A pretty-formatted summary of the outcome is returned as the verdict, for logging.
 func (r resourceTransitioner[T]) handleRequested(
 	requested T,