Add docs

Signed-off-by: asoliman <[email protected]>

shared/sub_plugin.go

@@ -11,6 +11,48 @@ type AttributedObservation[ObservationType any] struct {
 	Observation ObservationType
 }
 
+// SubPlugin This interface is to create multiple SubPlugins/Processors under OCR plugin.
+// The idea is to separate the logic of different types of observations and outcomes into separate processors.
+// This makes it easier to manage and test the logic of each type of observation/outcome without affecting each others
+// Some of them will implement state machines (e.g. merkleroot), others might implement simpler logic. (e.g. token)
+// The OCR plugin becomes a coordinator/collector of these SubPlugins.
+// Example Pseudo code:
+//
+//	OCRPlugin {
+//	  nodeID
+//	  merkleProcessor
+//	  tokenProcessor
+//	  feeProcessor
+//	  ...
+//	}
+//
+//	OCRPlugin.Observer {
+//	  mObs := merkleProcessor.Observer
+//	  tObs := tokenProcessor.Observer
+//	  fObs := feeProcessor.Observer
+//	  return Observation{mObs, tObs, fObs}
+//	}
+//	OCRPlugin.Validate {
+//	  mObs := merkleProcessor.Validate
+//	  tObs := tokenProcessor.Validate
+//	  fObs := feeProcessor.Validate
+//	  check errors for each
+//	  return nil
+//	}
+//	OCRPlugin.Outcome {
+//	  mOut := merkleProcessor.Outcome
+//	  tOut := tokenProcessor.Outcome
+//	  fOut := feeProcessor.Outcome
+//	  return Outcome{mOut, tOut, fOut}
+//	}
+//
+//	OCRPlugin.Report {
+//		return Report{mOut.X, tOut.Y, fOut.Z}
+//	}
+//
+// Notice all interface functions are using prevOutcome instead of outCtx.
+// We're interested in the prevOutcome, and it makes it easier to have all decoding on the top level (OCR plugin),
+// otherwise there might be cyclic dependencies or just complicating the code more.
 type SubPlugin[QueryType any, ObservationType any, OutcomeType any] interface {
 	Query(ctx context.Context, prevOutcome OutcomeType) (QueryType, error)
 	Observation(ctx context.Context, prevOutcome OutcomeType, query QueryType) (ObservationType, error)