[nongnu] elpa/geiser 2d3e4f9b3a 1/2: clarifications on geiser-custom--defcustom

[ELPA Syncer]

branch: elpa/geiser
commit 2d3e4f9b3a83e4c42139e6b7b7ce84490c80d1eb
Author: jao <jao@gnu.org>
Commit: jao <jao@gnu.org>

    clarifications on geiser-custom--defcustom
    
    In particular, removing a misleading FIXME comment that led to merge 
proposal
    !22, and adding comments explaining why those changes would alter
    geiser-reload's behaviour.
---
 elisp/geiser-custom.el | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/elisp/geiser-custom.el b/elisp/geiser-custom.el
index 4b42d910fa..7125f11ecf 100644
--- a/elisp/geiser-custom.el
+++ b/elisp/geiser-custom.el
@@ -1,6 +1,6 @@
 ;;; geiser-custom.el -- customization utilities  -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2009, 2010, 2012 Jose Antonio Ortega Ruiz
+;; Copyright (C) 2009, 2010, 2012, 2024 Jose Antonio Ortega Ruiz
 
 ;; This program is free software; you can redistribute it and/or
 ;; modify it under the terms of the Modified BSD License. You should
@@ -31,6 +31,10 @@
   :group 'faces)
 
 (defmacro geiser-custom--defface (face def group doc)
+  "Utility macro to define geiser.
+This is a very simple macro ensuring all geiser faces follow a common
+naming pattern and are added to a common group besides the one provided
+in the macro arguments."
   (declare (doc-string 4) (indent 1))
   (let ((face (intern (format "geiser-font-lock-%s" face))))
     `(defface ,face (face-default-spec ,def)
@@ -50,11 +54,14 @@
 
 (defmacro geiser-custom--defcustom (name &rest body)
   "Like `defcustom' but also put NAME on an internal list.
-That list is used by `geiser-reload' to preserve the values
-of the listed variables.  It is not used for anything else."
-  ;; FIXME Remembering the value like this is not actually
-  ;; necessary.  Evaluating `defcustom' always preserves the
-  ;; existing value, if any.
+That list is used by `geiser-reload' to preserve the values of the
+listed variables.  It is not used for anything else.
+
+Note that, even though defcustom preserves the existing value of a
+variable if it's already defined, geiser-reload unloads all geiser
+features and therefore undefines all defined variables: we keep this
+list of values around to be able to restore them after loading
+a (presumably) new version of geiser after that unloading."
   (declare (doc-string 3) (debug (name body)) (indent 2))
   `(progn
      (geiser-custom--memoize ',name)