From 72e45056209f79d1a944ae7810b831cfc62f9d49 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sun, 21 Jul 2019 15:09:54 +0100
Subject: [PATCH 2/3] Document value of notifications-notify on failure

* doc/lispref/os.texi (Desktop Notifications):
* lisp/notifications.el (notifications-notify): Document return
value of notifications-notify on failure, e.g. when D-Bus support is
not available.
---
 doc/lispref/os.texi   | 25 ++++++++++++++-----------
 lisp/notifications.el | 11 +++++++----
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index fef954eb7a..bc01f3722f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2644,22 +2644,25 @@ Desktop Notifications
 Which parameters are accepted by the notification server can be
 checked via @code{notifications-get-capabilities}.
 
-This function returns a notification id, an integer, which can be used
-to manipulate the notification item with
-@code{notifications-close-notification} or the @code{:replaces-id}
-argument of another @code{notifications-notify} call.  For example:
+If successful, this function returns a notification ID, an integer,
+which can be used to manipulate the notification item with
+@code{notifications-close-notification} or as the @code{:replaces-id}
+argument of another @code{notifications-notify} call.  Otherwise, if
+sending the notification failed, this function returns @code{nil}.
+This may happen when D-Bus or notification support is not available,
+for example.
+
+Here is an example demonstrating the use of action callbacks:
 
 @example
 @group
 (defun my-on-action-function (id key)
   (message "Message %d, key \"%s\" pressed" id key))
-     @result{} my-on-action-function
 @end group
 
 @group
 (defun my-on-close-function (id reason)
   (message "Message %d, closed due to \"%s\"" id reason))
-     @result{} my-on-close-function
 @end group
 
 @group
@@ -2667,15 +2670,15 @@ Desktop Notifications
  :title "Title"
  :body "This is <b>important</b>."
  :actions '("Confirm" "I agree" "Refuse" "I disagree")
- :on-action 'my-on-action-function
- :on-close 'my-on-close-function)
+ :on-action #'my-on-action-function
+ :on-close #'my-on-close-function)
      @result{} 22
 @end group
 
 @group
-A message window opens on the desktop.  Press ``I agree''.
-     @result{} Message 22, key "Confirm" pressed
-        Message 22, closed due to "dismissed"
+A message window opens on the desktop.  Press @samp{I agree}.
+     @print{} Message 22, key "Confirm" pressed
+     @print{} Message 22, closed due to "dismissed"
 @end group
 @end example
 @end defun
diff --git a/lisp/notifications.el b/lisp/notifications.el
index 1d250e2d92..241f127b11 100644
--- a/lisp/notifications.el
+++ b/lisp/notifications.el
@@ -198,10 +198,13 @@ notifications-notify
 Which parameters are accepted by the notification server can be
 checked via `notifications-get-capabilities'.
 
-This function returns a notification id, an integer, which can be
-used to manipulate the notification item with
-`notifications-close-notification' or the `:replaces-id' argument
-of another `notifications-notify' call."
+If successful, this function returns a notification ID, an
+integer, which can be used to manipulate the notification item
+with `notifications-close-notification' or as the `:replaces-id'
+argument of another `notifications-notify' call.  Otherwise, if
+sending the notification failed, this function returns nil.  This
+may happen when D-Bus or notification support is not available,
+for example."
   (with-demoted-errors
     (let ((bus (or (plist-get params :bus) :session))
 	  (title (plist-get params :title))
-- 
2.20.1