[FR] org-colview.el, add annotation for functions summary-types

[Sławomir Grochowski]

Dear all,

When the user wants to add a new column (or edit an existing one), he
executes the command `org-columns-new'. Then he can enter or select a few
'column attributes' (see in manual 
https://orgmode.org/org.html#Column-attributes-1).
One of the attributes is "SUMMARY-TYPE". This attribute can be selected
from the list of very enigmatic symbols such as "+", "$", "X"
which do not convey any information to the user. So, I have prepared a
solution that will address this issue.

For each symbol, the 'docstring' of the function assigned to that symbol
will be displayed. For example: 
"+ -- Compute the sum of VALUES."  
"$ -- Compute the sum of VALUES, with two decimals."

What do you think about this solution? 
I also included a question in the commit message regarding the function
`org-columns--first-line-docstring' that I created.

Patch below:

>From 1725dddfc6e574737f1b79f2ba93d5fa6b09cffb Mon Sep 17 00:00:00 2001
From: Slawomir Grochowski <slawomir.grochowski@gmail.com>
Date: Sat, 3 Aug 2024 19:53:25 +0200
Subject: [PATCH] lisp/org-colview.el: add annotation for summary-types

* org-colview.el (org-columns--first-line-docstring): add function that
retrieves the first line of function's docstring.
I have not found a function that would do such a simple thing, it seems
to me that such functionality is often used but there is no special
function for it? I couldn't find one, so I wrote my own. But it is a
general-purpose function and should not be located in org-colview.

(org-columns--summary-types-annotate): add function that return
annotation for one of the summary-type function in
`org-columns-summary-types-all'.
(org-columns-new): refactor: extract variable (append
org-columns-summary-types org-columns-summary-types-default) to
`org-columns-summary-types-all' because it is used in two places.
---
 lisp/org-colview.el | 39 ++++++++++++++++++++++++++++++---------
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/lisp/org-colview.el b/lisp/org-colview.el
index ed4d1ee16..50fb72121 100644
--- a/lisp/org-colview.el
+++ b/lisp/org-colview.el
@@ -953,6 +953,24 @@ When COLUMNS-FMT-STRING is non-nil, use it as the column 
format."
              (goto-char (car entry))
              (org-columns--display-here (cdr entry)))))))))
 
+(defun org-columns--first-line-docstring (fun)
+  "Return the first line of the documentation string of FUN."
+  (let* ((docstring (documentation fun))
+         (first-line (car (split-string docstring "\n"))))
+    first-line))
+
+(defun org-columns--summary-types-annotate (fun)
+  "Return annotation for one of the FUN in `org-columns-summary-types-all'.
+
+If FUN is not empty, retrieves the first line of the docstring for FUN
+from the `org-columns-summary-types-all', formats it, and decorates it
+with the `completions-annotations` face."
+  (when (not (string-empty-p fun))
+    (format " -- %s"
+            (propertize (org-columns--first-line-docstring
+                         (cdr (assoc fun org-columns-summary-types-all)))
+                        'face 'completions-annotations))))
+
 (defun org-columns-new (&optional spec &rest attributes)
   "Insert a new column, to the left of the current column.
 Interactively fill attributes for new column.  When column format
@@ -980,15 +998,18 @@ details."
                                        (number-to-string (nth 2 spec))))))
                           (and (org-string-nw-p w) (string-to-number w)))
                         (org-string-nw-p
-                         (completing-read
-                          "Summary: "
-                          (delete-dups
-                           (cons '("") ;Allow empty operator.
-                                 (mapcar (lambda (x) (list (car x)))
-                                         (append
-                                          org-columns-summary-types
-                                          org-columns-summary-types-default))))
-                          nil t (nth 3 spec)))
+                          (let* ((completion-extra-properties
+                                 '(:annotation-function 
org-columns--summary-types-annotate))
+                                (org-columns-summary-types-all (append
+                                                               
org-columns-summary-types
+                                                               
org-columns-summary-types-default)))
+                           (completing-read
+                            "Summary: "
+                            (delete-dups
+                             (cons '("") ;Allow empty operator.
+                                   (mapcar (lambda (x) (list (car x)))
+                                           org-columns-summary-types-all)))
+                            nil t (nth 3 spec))))
                         (org-string-nw-p
                          (read-string "Format: " (nth 4 spec))))))))
     (if spec
-- 
2.30.2


Regards,
-- 
Slawomir Grochowski