Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

notifications.go

@@ -41,7 +41,10 @@ func (n AppAPINotifications) ocsClient() OCSClient {
 	return c
 }
 
-// Send creates a Notification for the Requesting user on the Credentials.
+// Send creates a Notification for Cred.UserID.
+// It returns an error when UserID or Subject is empty, or when the OCS call fails.
+// AppAPI notification OCS accepts Subject, Message, Link, and rich-object
+// parameters. It does not accept actions or a custom icon.
 func (n AppAPINotifications) Send(notif Notification) error {
 	if n.Cred.UserID == "" {
 		return fmt.Errorf("notification recipient user id is required")
@@ -49,7 +52,9 @@ func (n AppAPINotifications) Send(notif Notification) error {
 	return n.send(n.Cred.UserID, notif)
 }
 
-// SendTo creates a Notification for userID, impersonating that Recipient.
+// SendTo creates a Notification for userID.
+// The OCS call is authenticated as that user via WithUser.
+// It returns an error when userID or Subject is empty, or when the OCS call fails.
 func (n AppAPINotifications) SendTo(userID string, notif Notification) error {
 	return n.send(userID, notif)
 }