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>

core/startos/src/action.rs

@@ -124,15 +124,20 @@ impl fmt::Display for ActionResultV0 {
 #[derive(Debug, Serialize, Deserialize, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct ActionResultV1 {
+    /// Primary text to display as the header of the response modal. e.g. "Success!", "Name Updated", or "Service Information", whatever makes sense
     pub title: String,
+    /// (optional) A general message for the user, just under the title
     pub message: Option<String>,
+    /// (optional) Structured data to present inside the modal
     pub result: Option<ActionResultValue>,
 }
 
 #[derive(Debug, Serialize, Deserialize, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct ActionResultMember {
+    /// A human-readable name or title of the value, such as "Last Active" or "Login Password"
     pub name: String,
+    /// (optional) A description of the value, such as an explaining why it exists or how to use it
     pub description: Option<String>,
     #[serde(flatten)]
     #[ts(flatten)]
@@ -145,12 +150,17 @@ pub struct ActionResultMember {
 #[serde(tag = "type")]
 pub enum ActionResultValue {
     Single {
+        /// The actual string value to display
         value: String,
+        /// Whether or not to include a copy to clipboard icon to copy the value
         copyable: bool,
+        /// Whether or not to also display the value as a QR code
         qr: bool,
+        /// Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information
         masked: bool,
     },
     Group {
+        /// An new group of nested values, experienced by the user as an accordion dropdown
         value: Vec<ActionResultMember>,
     },
 }

core/startos/src/db/model/package.rs

@@ -322,13 +322,25 @@ pub enum AllowedStatuses {
 #[serde(rename_all = "camelCase")]
 #[model = "Model<Self>"]
 pub struct ActionMetadata {
+    /// A human-readable name
     pub name: String,
+    /// A detailed description of what the action will do
     pub 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
     pub warning: Option<String>,
     #[serde(default)]
+    /// 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.
     pub 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
     pub allowed_statuses: AllowedStatuses,
     pub has_input: bool,
+    /// If provided, this action will be nested under a header of this value, along with other actions of the same group
     pub group: Option<String>,
 }