From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 18 Nov 2023 07:01:30 +0000 (+0200)
Subject: ; Improve documentation of recently added functions
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ae06e0275d6197e82eae5b8cb9bb30d33b863cee;p=emacs.git

; Improve documentation of recently added functions

* src/androidfns.c (Fandroid_external_storage_available_p)
(Fandroid_request_storage_access):
* lisp/term/android-win.el (android-after-splash-screen): Improve
and clarify wording of doc strings.
---

diff --git a/lisp/term/android-win.el b/lisp/term/android-win.el
index bcf49da1225..36470097b40 100644
--- a/lisp/term/android-win.el
+++ b/lisp/term/android-win.el
@@ -404,9 +404,9 @@ If storage permissions are as yet denied to Emacs, insert a short
 notice to that effect, followed by a button that enables the user
 to grant such permissions.
 
-FANCY-P controls if the inserted notice should be displayed in a
-variable space consequent on its being incorporated within the
-fancy splash screen."
+FANCY-P non-nil means the notice will be displayed with faces, in
+the style appropriate for its incorporation within the fancy splash
+screen display; see `francy-splash-insert'."
   (unless (android-external-storage-available-p)
     (if fancy-p
         (fancy-splash-insert
diff --git a/src/androidfns.c b/src/androidfns.c
index 785587d9282..aeba9d897ad 100644
--- a/src/androidfns.c
+++ b/src/androidfns.c
@@ -3101,7 +3101,7 @@ within the directory `/content/storage'.  */)
 DEFUN ("android-external-storage-available-p",
        Fandroid_external_storage_available_p,
        Sandroid_external_storage_available_p, 0, 0, 0,
-       doc: /* Return whether Emacs is entitled to access external storage.
+       doc: /* Return non-nil if Emacs is entitled to access external storage.
 Return nil if the requisite permissions for external storage access
 have not been granted to Emacs, t otherwise.  Such permissions can be
 requested by means of the `android-request-storage-access'
@@ -3117,13 +3117,13 @@ absent these permissions.  */)
 
 DEFUN ("android-request-storage-access", Fandroid_request_storage_access,
        Sandroid_request_storage_access, 0, 0, "",
-       doc: /* Request rights to access external storage.
+       doc: /* Request permissions to access external storage.
 
-Return nil whether access is accorded or not, immediately subsequent
-to displaying the permissions request dialog.
+Return nil regardless of whether access permissions are granted or not,
+immediately after displaying the permissions request dialog.
 
-`android-external-storage-available-p' (which see) ascertains if Emacs
-has received such rights.  */)
+Use `android-external-storage-available-p' (which see) to verify
+whether Emacs has actually received such access permissions.  */)
   (void)
 {
   android_request_storage_access ();