emacs-super-duper-yes-or-no

commit b51897b96ae55a361ced056058af6edee5dc6655
parent 00bb404197f591cd783950a5e854d7d3b5ced3a9
Author: Yuval Langer <yuvallangerontheroad@gmail.com>
Date:   Sat,  7 Oct 2023 21:59:27 +0300

Add some types and groups to the defcustoms and improve docstrings.

Diffstat:
M
super-duper-yes-or-no.el
 | 
58
+++++++++++++++++++++++++++++++++++++++++-----------------

1 file changed, 41 insertions(+), 17 deletions(-)
diff --git a/super-duper-yes-or-no.el b/super-duper-yes-or-no.el
@@ -41,8 +41,12 @@
 
 ;;; Code:
 
+(require 'cl-lib)
+
 (defcustom sd-number-of-words 2
-  "Number of words in the `sd-yes-or-no-words-p' words sequences.")
+  "Number of words in the `sd-yes-or-no-words-p' words sequences."
+  :type 'natnum
+  :group 'super-duper-yes-or-no)
 
 (defvar sd-words
   ["aaaaa"
@@ -53,24 +57,36 @@
 
 (defcustom sd-upper-case-phrase-for-yes
   "If you understand what you're doing, enter the capitalized letters here for \"yes\""
-  "Phrase to be used by the \"yes\" prong of `sd-yes-or-no-toggle-case-p'.")
+  "Phrase to be used by the \"yes\" prong of `sd-yes-or-no-toggle-case-p'."
+  :type 'string
+  :group 'super-duper-yes-or-no)
 
 (defcustom sd-upper-case-phrase-for-no
   "If you understand what you're doing, enter the capitalized letters here for \"no\""
-  "Phrase to be used by the \"no\" prong of `sd-yes-or-no-toggle-case-p'.")
+  "Phrase to be used by the \"no\" prong of `sd-yes-or-no-toggle-case-p'."
+  :type 'string
+  :group 'super-duper-yes-or-no)
 
 (defcustom sd-number-of-case-toggle-characters 4
-  "Number of English ASCII chars to be toggled in each of the two phrases provided in `sd-yes-or-no-toggle-case-p'.")
+  "Number of English ASCII chars toggled in a phrase.
+
+This number is used in `sd-yes-or-no-toggle-case-p'."
+  :type 'natnum
+  :group 'super-duper-yes-or-no)
 
 (defcustom sd-arithmetic-problem-minimum
   0
-  "Smallest integer to be used in `sd-yes-or-no-arithmetic-problem-p'.")
+  "Smallest integer to be used in `sd-yes-or-no-arithmetic-problem-p'."
+  :type 'integer
+  :group 'super-duper-yes-or-no)
 
 (defcustom sd-arithmetic-problem-maximum
   10
-  "Biggest integer to be used in `sd-yes-or-no-arithmetic-problem-p'.")
+  "Biggest integer to be used in `sd-yes-or-no-arithmetic-problem-p'."
+  :type 'integer
+  :group 'super-duper-yes-or-no)
 
-(defvar sd--arithmetic-problem-template
+(defcustom sd--arithmetic-problem-template
   '(+ (* 0 0)
       (* 0 0))
   "Template used to create arithmetic problems.
@@ -78,7 +94,9 @@
 Used by `sd-yes-or-no-arithmetic-problem-p'.
 
 The atomic arguments are replaced by integers and the functions
-stay unchanged.")
+stay unchanged."
+  :type 'list
+  :group 'super-duper-yes-or-no)
 
 (defun sd--randint (minimum maximum)
   "Return an integer between MINIMUM (inclusive) and MAXIMUM (exclusive)."
@@ -130,13 +148,12 @@ Used in super-duper-yes-or-no-words-p function."
 (defun sd--list-intersperse (input-list intersperser)
   "Return INPUT-LIST interspersed with INTERSPERSER.
 
-Example:
-
-\(sd--list-intersperse '(a b c) 'd)
+Examples:
 
-Will result with:
-
-'(a d b d c)"
+\\='(sd--list-intersperse \\='() \\='d) returns \\='()
+\\='(sd--list-intersperse \\='(a) \\='d) returns \\='(a)
+\\='(sd--list-intersperse \\='(a b) \\='d) returns \\='(a d b)
+\\='(sd--list-intersperse \\='(a b c) \\='d) returns \\='(a d b d c)"
   (cond
    ((null input-list)
     '())
@@ -151,7 +168,8 @@ Will result with:
 (defun sd-yes-or-no-words-p (prompt)
   "Ask user a yes or no question.
 
-Display in minibuffer PROMPT followed by two sequences of words, one for yes and the other for no."
+Display in minibuffer PROMPT followed by two sequences of words,
+one for yes and the other for no."
   (cl-loop
    for wanted-yes-or-no =
    (super-duper-yes-or-no--make-random-yes-or-no-input-pair
@@ -195,7 +213,12 @@ Display in minibuffer PROMPT followed by two sequences of words, one for yes and
           wanted-yes-string)))
 
 (defun sd--toggle-char-case (our-char)
-  "Return the downcase of OUR-CHAR if it is uppercase, otherwise the uppercase version."
+  "Return the opposite case of OUR-CHAR.
+
+Examples:
+
+- (sd--toggle-char-case ?a) returns ?A
+- (sd--toggle-char-case ?B) returns ?b"
   (cond
    ((char-uppercase-p our-char)
     (downcase our-char))
@@ -276,7 +299,8 @@ the toggle count AND they are not toggled."
 Display in minibuffer PROMPT followed by two lines, one for yes
 and the other for no.  Each of those two lines have a sequence of
 uppercase letters sprinkled inside.  If you want to answer yes,
-write in sequence the uppercase letters of the first line, otherwise, the uppercase letters of the second."
+write in sequence the uppercase letters of the first line,
+otherwise, the uppercase letters of the second."
   (cl-loop
    for wanted-yes-prompt =
    (sd--randomly-toggle-string-case