go-nativenotify

commit 6261410571dec47ea327669f15cbcccb95ee9b4f
parent e10a42b65df41d825a16058e4607f42f4366b000
Author: Jack Mordaunt <jackmordaunt.dev@gmail.com>
Date:   Fri, 17 Jan 2025 14:21:17 +0800

notify: describe how fields are used

Ensure that we communicate the importance of certain fields and how they
will be used.

Signed-off-by: Jack Mordaunt <jackmordaunt.dev@gmail.com>

Diffstat:
M
notify.go
 | 
45
+++++++++++++++++++++++++++++++--------------

1 file changed, 31 insertions(+), 14 deletions(-)
diff --git a/notify.go b/notify.go
@@ -22,14 +22,27 @@ import (
 
 // Callback is executed when the user interacts with a given notification.
 //
-// [userData] contains user input data, which is either text input, the
-// app payload for a button, or the app payload from the parent notification.
-type Callback func(err error, id string, userData map[string]string)
+// [id] names the parent notification that was activated.
+//
+// [data] contains user input data. Either the text input, the button payload
+// or the parent notification payload. Data should be inspected to understand
+// what part of the notification was activated.
+type Callback func(err error, id string, data map[string]string)
 
 // Notification describes the notification.
 type Notification struct {
+	// ID names this notification. This value will appear as the first string argument
+	// to the callback.
 	ID string
 
+	// AppPayload is passed to the callback upon activation under the key "default".
+	// No matter what part of the notification was activated, this payload will always
+	// be provided to the callback.
+	AppPayload string
+
+	// Callback is called upon activation.
+	Callback Callback
+
 	// Title text of the notification.
 	Title string
 
@@ -40,36 +53,40 @@ type Notification struct {
 	// All OS accept .png, other formats vary.
 	Icon string
 
-	// AppPayload is passed to the callback upon activation.
-	AppPayload string
-
 	// TextActions are for getting textual input from the user.
 	// Not supported on Linux.
 	TextActions []TextAction
 
 	// ButtonActions are for getting button input from the user.
 	ButtonActions []ButtonAction
-
-	// Callback is called upon activation.
-	Callback Callback
 }
 
 // TextAction describes a text input.
 // It might have an associated button.
 // The user input text is passed to the callback on activation.
+// Not all OS support this.
 type TextAction struct {
-	ID              string
-	Title           string
+	// ID names the action. The user text will appear in the user data keyed by this ID.
+	ID string
+	// Title describes the title text of this action.
+	Title string
+	// PlaceholderHint will appear as the placeholder text within the text input.
+	// Not all OS support this.
 	PlaceholderHint string
-	ButtonLabel     string
+	// ButtonLabel describes the content of any related button that is associated with
+	// the text input. Not all OS support this.
+	ButtonLabel string
 }
 
 // ButtonAction describes a button input.
 // [AppPayload] is passed to the callback on activation.
 type ButtonAction struct {
-	ID         string
-	LabelText  string
+	// ID names the action. The [AppPayload] will appear in the user data keyed by this ID.
+	ID string
+	// AppPayload is provided to the callback if this action is activated.
 	AppPayload string
+	// LabelText describes the text content of this button action.
+	LabelText string
 }
 
 // Config is a fat-union of the various initialization data required by each