chore: improve comments in Events ui code

Author: starpit

plugins/plugin-codeflare/src/controller/events/Events.tsx

@@ -31,6 +31,7 @@ interface EventState {
   torchEvents: TorchEvent[]
 }
 
+/** State for the `<Events/>` component */
 type State = EventState & {
   /** Total number of Kubernetes events */
   nKubeEvents: number
@@ -48,6 +49,7 @@ type State = EventState & {
   catastrophicError?: Error
 }
 
+/** Props for the `<Events/>` component */
 type Props = EventState & {
   /** Follow kube events? */
   onKube?(eventType: "data", cb: (data: any) => void): void
@@ -61,7 +63,11 @@ type Props = EventState & {
 
 /**
  * This component manages the `Event` state for the events UI. It uses
- * the `Grid` component to render the UI.
+ * the `<Grid/>` component to render the UI, and requires a controller
+ * (see below) to feed it an initial set of parsed `Event` objects,
+ * and a stream of unparsed log lines. (why unparsed for the streaming
+ * case? because some kinds of events require some recent
+ * history/context in order to be meaningfully parsed).
  *
  */
 class Events extends React.PureComponent<Props, State> {
@@ -170,6 +176,12 @@ class Events extends React.PureComponent<Props, State> {
   }
 }
 
+/**
+ * Controller portion of the events UI. It will set up the data
+ * streams, and feed parsed events to the `<Events/>` component. That
+ * component will manage the state of the events, and in turn pass off
+ * to the `<Grid/>` component for final rendering.
+ */
 async function eventsUI(filepath: string, REPL: Arguments["REPL"]) {
   const jobFilepath = join(expand(filepath), "logs/job.txt")
   const kubeFilepath = join(expand(filepath), "events/kubernetes.txt")

plugins/plugin-codeflare/src/controller/events/index.ts

@@ -16,7 +16,7 @@
 
 import { Registrar } from "@kui-shell/core"
 
-/** Register Kui Commands for rendering dashboard event UIs */
+/** Command registration part of the Events UI */
 export default function registerEventCommands(registrar: Registrar) {
   registrar.listen("/chart/events", (args) => import("./Events").then((_) => _.default(args)), { needsUI: true })
 }

plugins/plugin-codeflare/src/controller/events/torch.ts

@@ -16,18 +16,20 @@
 
 import Event from "./Event"
 
+/** The Torch events that we currently model */
 type EventType =
   | "Data Fetch from Upstream"
   | "Data Store in Cache"
   | "Data Fetch from Cache"
   | "Data Uncompress"
-  | "Evaluation"
-  | "EvaluationStep"
-  | "Epoch"
-  | "Iteration"
-  | "Marker"
-type Detail = { epoch: number; step: number; nSteps: number; ip: string }
-export type TorchEvent = Event<EventType, Detail>
+  | "Evaluation" // marks the beginning of an Evaluation stage
+  | "EvaluationStep" // a step in an Evaluation stage; 2/9, 3/9, ...
+  | "Epoch" // a torch training Epoch
+  | "Iteration" // a torch training Iteration
+  | "Marker" // currently used to manufacture a timestamp for non-timestamped events, sigh
+
+/** A `TorchEvent` is a subclass of `Event` with our own `EventType` and our own event details */
+export type TorchEvent = Event<EventType, { epoch: number; step: number; nSteps: number; ip: string }>
 
 function findPrevious(
   M: TorchEvent[],