feat: added documentation comments

ref: N25B-450

src/pages/VisProgPage/visualProgrammingUI/components/EditorWarnings.tsx

@@ -27,6 +27,9 @@ export type WarningSeverity =
   | 'WARNING' // Acceptable, but probably undesirable behavior
   | 'ERROR' // Prevents running program, should be fixed before running program is allowed
 
+/**
+ * warning scope, include a handleId if the warning is handle specific
+ */
 export type WarningScope = {
   id: string;
   handleId?: string;
@@ -61,11 +64,26 @@ type ZustandSet = (partial: Partial<FlowState> | ((state: FlowState) => Partial<
 type ZustandGet = () => FlowState;
 
 export type EditorWarningRegistry = {
+  /**
+   * stores all editor warnings
+   */
   editorWarningRegistry: WarningRegistry;
+  /**
+   * index of warnings by severity
+   */
   severityIndex: SeverityIndex;
 
+  /**
+   * gets all warnings and returns them as a list of warnings
+   * @returns {EditorWarning[]}
+   */
   getWarnings: () => EditorWarning[];
 
+  /**
+   * gets all warnings with the current severity
+   * @param {WarningSeverity} warningSeverity
+   * @returns {EditorWarning[]}
+   */
   getWarningsBySeverity: (warningSeverity: WarningSeverity) => EditorWarning[];
 
   /**
@@ -95,6 +113,10 @@ export type EditorWarningRegistry = {
 
 // --| implemented logic |--
 
+/**
+ * the id to use for global editor warnings
+ * @type {string}
+ */
 export const globalWarning = "GLOBAL_WARNINGS";
 
 export function editorWarningRegistry(get: ZustandGet, set: ZustandSet) : EditorWarningRegistry { return {
@@ -205,7 +227,11 @@ export function editorWarningRegistry(get: ZustandGet, set: ZustandSet) : Editor
 }}
 
 
-// returns a summary of the warningRegistry
+
+/**
+ * returns a summary of the warningRegistry
+ * @returns {{info: number, warning: number, error: number, isValid: boolean}}
+ */
 export function warningSummary() {
   const {severityIndex, isProgramValid} = useFlowStore.getState();
   return {

src/pages/VisProgPage/visualProgrammingUI/components/WarningSidebar.tsx

@@ -9,6 +9,12 @@ import {
 } from "./EditorWarnings.tsx";
 import styles from "./WarningSidebar.module.css";
 
+/**
+ * the warning sidebar, shows all warnings
+ *
+ * @returns {React.JSX.Element}
+ * @constructor
+ */
 export function WarningsSidebar() {
   const warnings = useFlowStore.getState().getWarnings();
   const [hide, setHide] = useState(false);
@@ -72,6 +78,14 @@ export function WarningsSidebar() {
   );
 }
 
+/**
+ * the header of the warning sidebar, contains severity filtering buttons
+ *
+ * @param {WarningSeverity | "ALL"} severityFilter
+ * @param {(severity: (WarningSeverity | "ALL")) => void} onChange
+ * @returns {React.JSX.Element}
+ * @constructor
+ */
 function WarningsHeader({
   severityFilter,
   onChange,
@@ -105,7 +119,13 @@ function WarningsHeader({
 }
 
 
-
+/**
+ *  the list of warnings in the warning sidebar
+ *
+ * @param {{warnings: EditorWarning[]}} props
+ * @returns {React.JSX.Element}
+ * @constructor
+ */
 function WarningsList(props: { warnings: EditorWarning[] }) {
   const splitWarnings = {
     global: props.warnings.filter(w => w.scope.id === globalWarning),
@@ -144,6 +164,13 @@ function WarningsList(props: { warnings: EditorWarning[] }) {
   );
 }
 
+/**
+ * a single warning in the warning sidebar
+ *
+ * @param {{warning: EditorWarning, key: string}} props
+ * @returns {React.JSX.Element}
+ * @constructor
+ */
 function WarningListItem(props: { warning: EditorWarning, key: string}) {
   const jumpToNode = useJumpToNode();
 
@@ -163,6 +190,10 @@ function WarningListItem(props: { warning: EditorWarning, key: string}) {
   );
 }
 
+/**
+ * moves the editor to the provided node
+ * @returns {(nodeId: string) => void}
+ */
 function useJumpToNode() {
   const { getNode, setCenter, getViewport } = useReactFlow();
   const { addSelectedNodes } = useStoreApi().getState();