corfu-margin-formatters: Document the requirements of the margin formatter

While well known to the maintainer and author of the kind-icon package, these
limitations have unfortunately been undocumented so far. See the related
discussions:

* https://github.com/LuigiPiucco/nerd-icons-corfu/issues/13
* https://github.com/minad/corfu/pull/508

The kind-icon package which satisfies the requirements correctly and preserves
Corfu popup alignment. It can serve as a reference implementation:

* https://github.com/jdtsmith/kind-icon

1 files changed, 6 insertions, 1 deletions

diff --git a/corfu.el b/corfu.el
index 223857b..844fd1f 100644
--- a/corfu.el
+++ b/corfu.el
@@ -145,7 +145,12 @@ separator: Only stay alive if there is no match and
 Each function of the list is called with the completion metadata as
 argument until an appropriate formatter is found.  The function should
 return a formatter function, which takes the candidate string and must
-return a string, possibly an icon."
+return a string, possibly an icon.  In order to preserve correct popup
+alignment, the length and display width of the returned string must
+precisely span the same number of fixed number of fixed-width characters
+of the fixed-width popup font, ideally one or two characters.  For
+example the kind-icon package returns a string of length two with a
+display width of two characters."
   :type 'hook)
 
 (defcustom corfu-sort-function #'corfu-sort-length-alpha