Clarify Gravatar docs

For discussion, see the following thread:
https://lists.gnu.org/archive/html/emacs-devel/2019-07/msg00528.html
* doc/misc/gnus.texi (X-Face): Fix cross-reference.
(Gravatars):
* lisp/gnus/gnus-gravatar.el (gnus-gravatar-too-ugly):
* lisp/image/gravatar.el (gravatar-cache-ttl, gravatar-rating)
(gravatar-size): Clarify user option descriptions.
(gravatar-retrieve, gravatar-retrieve-synchronously): Document
return value.

2 files changed, 30 insertions, 8 deletions

diff --git a/lisp/gnus/gnus-gravatar.el b/lisp/gnus/gnus-gravatar.el
index d271a52f908..19cbf529c65 100644
--- a/lisp/gnus/gnus-gravatar.el
+++ b/lisp/gnus/gnus-gravatar.el
@@ -46,7 +46,8 @@ If nil, default to `gravatar-size'."
   :group 'gnus-gravatar)
 
 (defcustom gnus-gravatar-too-ugly gnus-article-x-face-too-ugly
-  "Regexp matching posters whose avatar shouldn't be shown automatically."
+  "Regexp matching posters whose avatar shouldn't be shown automatically.
+If nil, show all avatars."
   :type '(choice regexp (const nil))
   :version "24.1"
   :group 'gnus-gravatar)
diff --git a/lisp/image/gravatar.el b/lisp/image/gravatar.el
index 2b106ba0675..76c1ac1644d 100644
--- a/lisp/image/gravatar.el
+++ b/lisp/image/gravatar.el
@@ -40,18 +40,35 @@
 
 ;; FIXME a time value is not the nicest format for a custom variable.
 (defcustom gravatar-cache-ttl (days-to-time 30)
-  "Time to live for gravatar cache entries."
+  "Time to live for gravatar cache entries.
+If a requested gravatar has been cached for longer than this, it
+is retrieved anew."
   :type '(repeat integer)
   :group 'gravatar)
 
-;; FIXME Doc is tautological.  What are the options?
 (defcustom gravatar-rating "g"
-  "Default rating for gravatar."
+  "Most explicit Gravatar rating level to allow.
+Some gravatars are rated according to how suitable they are for
+different audiences.  The supported rating levels are, in order
+of increasing explicitness, the following:
+
+\"g\"  - Suitable for any audience.
+\"pg\" - May contain rude gestures, provocatively dressed
+       individuals, mild profanity, or mild violence.
+\"r\"  - May contain harsh profanity, intense violence, nudity,
+       or hard drug use.
+\"x\"  - May contain hardcore sexual imagery or extremely
+       disturbing violence.
+
+Each level covers itself as well as all less explicit levels.
+For example, setting this variable to \"pg\" will allow gravatars
+rated either \"g\" or \"pg\"."
   :type 'string
   :group 'gravatar)
 
 (defcustom gravatar-size 32
-  "Default size in pixels for gravatars."
+  "Gravatar size in pixels to request.
+Valid sizes range from 1 to 2048 inclusive."
   :type 'integer
   :group 'gravatar)
 
@@ -104,8 +121,10 @@ If no image available, return 'error."
 
 ;;;###autoload
 (defun gravatar-retrieve (mail-address cb &optional cbargs)
-  "Retrieve MAIL-ADDRESS gravatar and call CB on retrieval.
-You can provide a list of argument to pass to CB in CBARGS."
+  "Asynchronously retrieve a gravatar for MAIL-ADDRESS.
+When finished, call CB as (apply CB GRAVATAR CBARGS),
+where GRAVATAR is either an image descriptor, or the symbol
+`error' if the retrieval failed."
   (let ((url (gravatar-build-url mail-address)))
     (if (gravatar-cache-expired url)
 	(let ((args (list url
@@ -126,7 +145,9 @@ You can provide a list of argument to pass to CB in CBARGS."
 
 ;;;###autoload
 (defun gravatar-retrieve-synchronously (mail-address)
-  "Retrieve MAIL-ADDRESS gravatar and returns it."
+  "Synchronously retrieve a gravatar for MAIL-ADDRESS.
+Value is either an image descriptor, or the symbol `error' if the
+retrieval failed."
   (let ((url (gravatar-build-url mail-address)))
     (if (gravatar-cache-expired url)
         (with-current-buffer (url-retrieve-synchronously url)