📝 Add docstrings to drjkl/byom-2

Docstrings generation was requested by @guill.

* #6969 (comment)

The following files were modified:

* `src/components/dialog/confirm/confirmDialog.ts`
* `src/composables/useFeatureFlags.ts`
* `src/platform/assets/services/assetService.ts`
* `src/services/dialogService.ts`
* `src/stores/dialogStore.ts`

Author: coderabbitai[bot]

src/components/dialog/confirm/confirmDialog.ts

@@ -10,6 +10,14 @@ interface ConfirmDialogOptions {
   footerProps?: ComponentAttrs<typeof ConfirmFooter>
 }
 
+/**
+ * Open a confirmation dialog composed of the standard confirm header, body, and footer.
+ *
+ * Forwards any provided `headerProps`, `props`, and `footerProps` to the corresponding components.
+ *
+ * @param options - Optional configuration with `headerProps`, `props`, and `footerProps` to customize the header, body, and footer components
+ * @returns A dialog handle representing the shown confirmation dialog
+ */
 export function showConfirmDialog(options: ConfirmDialogOptions = {}) {
   const dialogStore = useDialogStore()
   const { headerProps, props, footerProps } = options
@@ -28,4 +36,4 @@ export function showConfirmDialog(options: ConfirmDialogOptions = {}) {
       }
     }
   })
-}
+}

src/composables/useFeatureFlags.ts

@@ -14,7 +14,15 @@ export enum ServerFeatureFlag {
 }
 
 /**
- * Composable for reactive access to server-side feature flags
+ * Provides reactive accessors for server-side feature flags.
+ *
+ * Exposes a readonly `flags` object containing convenience getters for known server feature keys
+ * and a `featureFlag` helper that returns a computed value for an arbitrary feature path,
+ * optionally using a supplied default when the feature is not present.
+ *
+ * @returns An object with:
+ *  - `flags`: a readonly reactive object with predefined getters for common server feature flags
+ *  - `featureFlag`: a generic function `(featurePath: string, defaultValue?) => ComputedRef<T>` that yields a computed feature value
  */
 export function useFeatureFlags() {
   const flags = reactive({
@@ -48,4 +56,4 @@ export function useFeatureFlags() {
     flags: readonly(flags),
     featureFlag
   }
-}
+}

src/platform/assets/services/assetService.ts

@@ -265,12 +265,10 @@ function createAssetService() {
   }
 
   /**
-   * Deletes an asset by ID
-   * Only available in cloud environment
+   * Delete the asset identified by `id` (cloud environments only).
    *
    * @param id - The asset ID (UUID)
-   * @returns Promise<void>
-   * @throws Error if deletion fails
+   * @throws Error if the server responds with a non-ok status; message includes the HTTP status
    */
   async function deleteAsset(id: string): Promise<void> {
     const res = await api.fetchApi(`${ASSETS_ENDPOINT}/${id}`, {
@@ -285,13 +283,14 @@ function createAssetService() {
   }
 
   /**
-   * Update metadata of an asset by ID
-   * Only available in cloud environment
+   * Update an asset's metadata by its ID.
+   *
+   * Only available in cloud environment.
    *
    * @param id - The asset ID (UUID)
-   * @param newData - The data to update
-   * @returns Promise<AssetItem>
-   * @throws Error if update fails
+   * @param newData - Partial metadata fields to apply to the asset
+   * @returns The updated AssetItem
+   * @throws Error if the server responds with a non-OK status or the response cannot be validated as an AssetItem
    */
   async function updateAsset(
     id: string,
@@ -406,4 +405,4 @@ function createAssetService() {
   }
 }
 
-export const assetService = createAssetService()
+export const assetService = createAssetService()

src/services/dialogService.ts

@@ -47,6 +47,11 @@ export type ConfirmationDialogType =
 export const useDialogService = () => {
   const dialogStore = useDialogStore()
 
+  /**
+   * Open the global missing-nodes dialog and forward the provided props to its content component.
+   *
+   * @param props - Props passed through to the MissingNodesContent component
+   */
   function showLoadWorkflowWarning(
     props: ComponentAttrs<typeof MissingNodesContent>
   ) {
@@ -73,6 +78,11 @@ export const useDialogService = () => {
     })
   }
 
+  /**
+   * Show the global missing-models warning dialog.
+   *
+   * @param props - Props forwarded to the MissingModelsWarning component
+   */
   function showMissingModelsWarning(
     props: ComponentAttrs<typeof MissingModelsWarning>
   ) {
@@ -103,6 +113,11 @@ export const useDialogService = () => {
     })
   }
 
+  /**
+   * Opens the global settings dialog with the About panel selected.
+   *
+   * Displays the settings dialog and sets its default inner panel to "about".
+   */
   function showAboutDialog() {
     dialogStore.showDialog({
       key: 'global-settings',
@@ -114,6 +129,13 @@ export const useDialogService = () => {
     })
   }
 
+  /**
+   * Shows the global execution error dialog populated from a websocket execution error message.
+   *
+   * Displays a dialog containing the error details from `executionError` and records a telemetry event when the dialog is closed.
+   *
+   * @param executionError - Websocket execution error message containing `exception_type`, `exception_message`, `node_id`, `node_type`, and `traceback`
+   */
   function showExecutionErrorDialog(executionError: ExecutionErrorWsMessage) {
     const props: ComponentAttrs<typeof ErrorDialogContent> = {
       error: {
@@ -140,6 +162,11 @@ export const useDialogService = () => {
     })
   }
 
+  /**
+   * Opens the global manager dialog using the default manager layout and styling and forwards props to the dialog content.
+   *
+   * @param props - Props to pass through to ManagerDialogContent (defaults to an empty object)
+   */
   function showManagerDialog(
     props: ComponentAttrs<typeof ManagerDialogContent> = {}
   ) {
@@ -184,9 +211,12 @@ export const useDialogService = () => {
   }
 
   /**
-   * Show a error dialog to the user when an error occurs.
-   * @param error The error to show
-   * @param options The options for the dialog
+   * Displays a global error dialog for the given error and tracks the dialog close event for telemetry.
+   *
+   * @param error - An Error or any value to display; if an Error is provided it will be parsed for message, stack trace, and extension file.
+   * @param options - Optional configuration for the dialog
+   * @param options.title - Title used as the exception type shown in the dialog
+   * @param options.reportType - Optional report type forwarded to the dialog for reporting purposes
    */
   function showErrorDialog(
     error: unknown,
@@ -412,15 +442,10 @@ export const useDialogService = () => {
   }
 
   /**
-   * Shows a dialog from a third party extension.
-   * @param options - The dialog options.
-   * @param options.key - The dialog key.
-   * @param options.title - The dialog title.
-   * @param options.headerComponent - The dialog header component.
-   * @param options.footerComponent - The dialog footer component.
-   * @param options.component - The dialog component.
-   * @param options.props - The dialog props.
-   * @returns The dialog instance and a function to close the dialog.
+   * Show a dialog provided by a third-party extension.
+   *
+   * @param options - Dialog configuration including `key`, optional `title`, header/footer components, dialog `component`, and `props` passed to the component.
+   * @returns An object with `dialog`, the dialog instance returned by the dialog store, and `closeDialog`, a function that closes the dialog using the provided `key`.
    */
   function showExtensionDialog(options: ShowDialogOptions & { key: string }) {
     return {
@@ -429,6 +454,13 @@ export const useDialogService = () => {
     }
   }
 
+  /**
+   * Toggles the global manager dialog's visibility.
+   *
+   * If the global manager dialog is open, it will be closed; otherwise it will be shown.
+   *
+   * @param props - Optional props to pass to the ManagerDialogContent when opening the dialog
+   */
   function toggleManagerDialog(
     props?: ComponentAttrs<typeof ManagerDialogContent>
   ) {
@@ -439,6 +471,11 @@ export const useDialogService = () => {
     }
   }
 
+  /**
+   * Toggles the global manager progress dialog: closes it if open, otherwise opens it.
+   *
+   * @param props - Optional props to pass to the ManagerProgressDialogContent when opening the dialog
+   */
   function toggleManagerProgressDialog(
     props?: ComponentAttrs<typeof ManagerProgressDialogContent>
   ) {
@@ -563,4 +600,4 @@ export const useDialogService = () => {
     showLayoutDialog,
     showNodeConflictDialog
   }
-}
+}

src/stores/dialogStore.ts

@@ -116,6 +116,13 @@ export const useDialogStore = defineStore('dialog', () => {
     }
   }
 
+  /**
+   * Closes the dialog identified by the given key or the currently active dialog when no key is provided.
+   *
+   * Invokes the dialog's `onClose` callback if present, removes the dialog from the stack, updates the active dialog key, and adjusts close-on-Escape handling. If no matching dialog is found this function is a no-op.
+   *
+   * @param options - Optional object with a `key` specifying which dialog to close; when omitted the active dialog is closed.
+   */
   function closeDialog(options?: { key: string }) {
     const targetDialog = options
       ? dialogStack.value.find((d) => d.key === options.key)
@@ -134,6 +141,14 @@ export const useDialogStore = defineStore('dialog', () => {
     updateCloseOnEscapeStates()
   }
 
+  /**
+   * Create and register a dialog instance from the given options and push it into the dialog stack.
+   *
+   * @param options - Configuration for the dialog. Must include a unique `key`. Other fields configure the component to render (`component`), optional `title`, optional `headerComponent`/`footerComponent` and their props, additional `props` for the content component, `dialogComponentProps` for dialog behavior, and an optional numeric `priority`.
+   * @returns The created dialog instance that was inserted into the store's stack.
+   *
+   * Side effects: enforces a maximum stack size of 10 by removing the oldest dialog when necessary, inserts the new dialog according to its priority, sets the dialog as the active one, and updates close-on-escape handling for the stack.
+   */
   function createDialog<
     H extends Component = Component,
     B extends Component = Component,
@@ -209,6 +224,12 @@ export const useDialogStore = defineStore('dialog', () => {
     })
   }
 
+  /**
+   * Opens the dialog described by `options` and ensures it is the active (top-most) dialog, creating a new dialog if one with the same key does not exist.
+   *
+   * @param options - Configuration for the dialog to show; may include a `key` to target an existing dialog or omit it to generate a new key
+   * @returns The dialog instance that was shown or created
+   */
   function showDialog<
     H extends Component = Component,
     B extends Component = Component,
@@ -262,4 +283,4 @@ export const useDialogStore = defineStore('dialog', () => {
     isDialogOpen,
     activeKey
   }
-})
+})