[elpa] externals/corfu 171b305 23/29: README: Add caveats section

[Stefan Monnier]

branch: externals/corfu
commit 171b305871d54eed5be4ae0eed27888cf1d2d423
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    README: Add caveats section
---
 README.org | 32 +++++++++++++++++++++++++-------
 corfu.el   |  5 +++--
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/README.org b/README.org
index 4940304..a47f8e5 100644
--- a/README.org
+++ b/README.org
@@ -35,17 +35,20 @@ completion may often be sufficient.
 - The popup must be summoned explicitly by =TAB=
 - The current candidate is inserted with =TAB= and selected with =RET=
 - Candidates sorting by prefix, string length and alphabetically
-- Completion is automatically left after candidate selection
+- Completion is automatically terminated after candidate selection
 - Filter string can contain arbitrary characters and spaces (needed
   when filtering with the [[https://github.com/oantolin/orderless][Orderless]] 
completion style)
 - Deferred completion style highlighting for performance
 
-Notable non-feature: Annotations are not supported, but could be added
-relatively easily (see the annotation branch). However annotations in the
-completion popup are a bit too much for my taste, in particular if one 
considers
-verbose annotations like documentation strings or annotations in the style of
-[[https://github.com/minad/marginalia][Marginalia]]. These annotations work 
better in Vertico or in the =*Completions*=
-buffer.
+Notable non-features:
+
++ Annotations are not supported, but could be added
+  relatively easily (see the annotation branch). However annotations in the
+  completion popup are a bit too much for my taste, in particular if one
+  considers verbose annotations like documentation strings or annotations in 
the
+  style of [[https://github.com/minad/marginalia][Marginalia]]. These 
annotations work better in Vertico or in the
+  =*Completions*= buffer.
++ Timer-based/Idle automatic completions are not supported.
 
 * Configuration
 
@@ -103,6 +106,21 @@ expressions are separated by spaces.
 You may also want to look into my 
[[https://github.com/minad/vertico][Vertico]] package, which provides a vertical
 minibuffer completion system. Vertico is the minibuffer counterpart of Corfu.
 
+* Caveats
+
+This package is experimental and new. I am not yet claiming that this package
+works correctly. There are a few known caveats.
+
++ Annotations are not supported.
++ Company enhancements are not supported (~company-docsig~, 
~company-location~, ...).
++ No caching, the completion table is called directly.
++ The =:exit-function= handling is probably insufficient.
++ The thin popup borders are only drawn if =line-spacing=nil=.
++ The abort handling could be improved. Undo the completion input?
++ The completion exit predicate is deliberatly ignored in order to
+  give the completion style full control.
++ Completion is terminated if there are no matches. Add optional confirmation?
+
 * Contributions
 
 Since this package is part of GNU ELPA, contributions require copyright
diff --git a/corfu.el b/corfu.el
index 68b462f..9dfb810 100644
--- a/corfu.el
+++ b/corfu.el
@@ -134,7 +134,7 @@
   (let ((lh (line-pixel-height)))
     (cons (round (* lh (frame-char-width)) (frame-char-height)) lh)))
 
-;; TODO Is there a better way to generate an image? Bitmap vector?
+;; XXX Is there a better way to generate an image? Bitmap vector?
 (defun corfu--border (w h color width)
   "Generate border with COLOR and WIDTH and image size W*H."
   (let ((row (funcall (if (< width 0) #'reverse #'identity)
@@ -325,7 +325,7 @@
            ;; Input after boundary is empty
            (not (and (= (car bounds) (length str))
                      (test-completion str table pred)))
-           ;; No candidates
+           ;; XXX Completion is terminated if there are no matches. Add 
optional confirmation?
            corfu--candidates
            ;; Single candidate
            (not (equal corfu--candidates (list str))))
@@ -420,6 +420,7 @@
                (newstr (concat (substring str 0 corfu--base)
                                (substring-no-properties (nth (max 0 
corfu--index) corfu--candidates)))))
     (completion--replace beg end newstr)
+    ;; XXX Is the :exit-function handling sufficient?
     (when-let (exit (plist-get corfu--extra-properties :exit-function))
       (funcall exit newstr 'finished))
     (completion-in-region-mode -1)))