From e45b3fc521acca47abdd2b9e491b9fbbd8d3e677 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Tue, 26 Oct 2021 23:17:29 +0200
Subject: [PATCH] Improve function documentation with text from XDG BDS spec

* lisp/xdg.el (xdg-config-home, xdg-cache-home, xdg-data-home)
(xdg-runtime-dir, xdg-config-dirs, xdg-data-dirs): Copy in the
text from the XDG Base Directory Specification to better explain
what these functions return.
---
 lisp/xdg.el | 66 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 60 insertions(+), 6 deletions(-)

diff --git a/lisp/xdg.el b/lisp/xdg.el
index 1f9fa6795e0..db890f9494b 100644
--- a/lisp/xdg.el
+++ b/lisp/xdg.el
@@ -50,30 +50,84 @@
          ,env))))
 
 (defun xdg-config-home ()
-  "Return the base directory for user specific configuration files."
+  "Return the base directory for user specific configuration files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CONFIG_HOME defines the base directory relative to
+    which user-specific configuration files should be stored.
+    If $XDG_CONFIG_HOME is either not set or empty, a default
+    equal to $HOME/.config should be used.\""
   (xdg--dir-home "XDG_CONFIG_HOME" "~/.config"))
 
 (defun xdg-cache-home ()
-  "Return the base directory for user specific cache files."
+  "Return the base directory for user specific cache files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CACHE_HOME defines the base directory relative to
+    which user-specific non-essential data files should be
+    stored.  If $XDG_CACHE_HOME is either not set or empty, a
+    default equal to $HOME/.cache should be used.\""
   (xdg--dir-home "XDG_CACHE_HOME" "~/.cache"))
 
 (defun xdg-data-home ()
-  "Return the base directory for user specific data files."
+  "Return the base directory for user specific data files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_DATA_HOME defines the base directory relative to which
+    user-specific data files should be stored.  If $XDG_DATA_HOME is
+    either not set or empty, a default equal to $HOME/.local/share
+    should be used.\""
   (xdg--dir-home "XDG_DATA_HOME" "~/.local/share"))
 
 (defun xdg-runtime-dir ()
-  "Return the value of $XDG_RUNTIME_DIR."
+  "Return the value of $XDG_RUNTIME_DIR.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_RUNTIME_DIR defines the base directory relative to
+    which user-specific non-essential runtime files and other
+    file objects (such as sockets, named pipes, ...) should be
+    stored.\""
   (getenv "XDG_RUNTIME_DIR"))
 
 (defun xdg-config-dirs ()
-  "Return the config directory search path as a list."
+  "Return the config directory search path as a list.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CONFIG_DIRS defines the preference-ordered set of base
+    directories to search for configuration files in addition to
+    the $XDG_CONFIG_HOME base directory.  The directories in
+    $XDG_CONFIG_DIRS should be seperated with a colon ':'.
+
+    \"If $XDG_CONFIG_DIRS is either not set or empty, a value equal to
+    /etc/xdg should be used.\""
   (let ((env (getenv "XDG_CONFIG_DIRS")))
     (if (or (null env) (string= env ""))
         '("/etc/xdg")
       (parse-colon-path env))))
 
 (defun xdg-data-dirs ()
-  "Return the data directory search path as a list."
+  "Return the data directory search path as a list.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_DATA_DIRS defines the preference-ordered set of base
+    directories to search for data files in addition to the
+    $XDG_DATA_HOME base directory.  The directories in
+    $XDG_DATA_DIRS should be seperated with a colon ':'.
+
+    \"If $XDG_DATA_DIRS is either not set or empty, a value equal
+    to /usr/local/share/:/usr/share/ should be used.\""
   (let ((env (getenv "XDG_DATA_DIRS")))
     (if (or (null env) (string= env ""))
         '("/usr/local/share/" "/usr/share/")
-- 
2.39.5