More SDK comments (#2796)

* sdk tweaks

* switch back to deeppartial

* WIP, update comments

* reinstall chesterton's fence

* more comments

* delete extra package.lock

* handle TODOs

---------

Co-authored-by: Aiden McClelland <me@drbonez.dev>

sdk/base/lib/osBindings/ActionMetadata.ts

@@ -3,11 +3,35 @@ import type { ActionVisibility } from "./ActionVisibility"
 import type { AllowedStatuses } from "./AllowedStatuses"
 
 export type ActionMetadata = {
+  /**
+   * A human-readable name
+   */
   name: string
+  /**
+   * A detailed description of what the action will do
+   */
   description: string
+  /**
+   * Presents as an alert prior to executing the action. Should be used sparingly but important if the action could have harmful, unintended consequences
+   */
   warning: string | null
+  /**
+   * One of: "enabled", "hidden", or { disabled: "" }
+   *   - "enabled" - the action is available be run
+   *   - "hidden" - the action cannot be seen or run
+   *   - { disabled: "example explanation" } means the action is visible but cannot be run. Replace "example explanation" with a reason why the action is disable to prevent user confusion.
+   */
   visibility: ActionVisibility
+  /**
+   * One of: "only-stopped", "only-running", "all"
+   *   - "only-stopped" - the action can only be run when the service is stopped
+   *   - "only-running" - the action can only be run when the service is running
+   *   - "any" - the action can only be run regardless of the service's status
+   */
   allowedStatuses: AllowedStatuses
   hasInput: boolean
+  /**
+   * If provided, this action will be nested under a header of this value, along with other actions of the same group
+   */
   group: string | null
 }

sdk/base/lib/osBindings/ActionResultMember.ts

@@ -1,15 +1,39 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
 export type ActionResultMember = {
+  /**
+   * A human-readable name or title of the value, such as "Last Active" or "Login Password"
+   */
   name: string
+  /**
+   * (optional) A description of the value, such as an explaining why it exists or how to use it
+   */
   description: string | null
 } & (
   | {
       type: "single"
+      /**
+       * The actual string value to display
+       */
       value: string
+      /**
+       * Whether or not to include a copy to clipboard icon to copy the value
+       */
       copyable: boolean
+      /**
+       * Whether or not to also display the value as a QR code
+       */
       qr: boolean
+      /**
+       * Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information
+       */
       masked: boolean
     }
-  | { type: "group"; value: Array<ActionResultMember> }
+  | {
+      type: "group"
+      /**
+       * An new group of nested values, experienced by the user as an accordion dropdown
+       */
+      value: Array<ActionResultMember>
+    }
 )

sdk/base/lib/osBindings/ActionResultV1.ts

@@ -2,7 +2,16 @@
 import type { ActionResultValue } from "./ActionResultValue"
 
 export type ActionResultV1 = {
+  /**
+   * Primary text to display as the header of the response modal. e.g. "Success!", "Name Updated", or "Service Information", whatever makes sense
+   */
   title: string
+  /**
+   * (optional) A general message for the user, just under the title
+   */
   message: string | null
+  /**
+   * (optional) Structured data to present inside the modal
+   */
   result: ActionResultValue | null
 }

sdk/base/lib/osBindings/ActionResultValue.ts

@@ -4,9 +4,27 @@ import type { ActionResultMember } from "./ActionResultMember"
 export type ActionResultValue =
   | {
       type: "single"
+      /**
+       * The actual string value to display
+       */
       value: string
+      /**
+       * Whether or not to include a copy to clipboard icon to copy the value
+       */
       copyable: boolean
+      /**
+       * Whether or not to also display the value as a QR code
+       */
       qr: boolean
+      /**
+       * Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information
+       */
       masked: boolean
     }
-  | { type: "group"; value: Array<ActionResultMember> }
+  | {
+      type: "group"
+      /**
+       * An new group of nested values, experienced by the user as an accordion dropdown
+       */
+      value: Array<ActionResultMember>
+    }