Trying to understand 'icomplete-in-buffer'

[Gabriel <gabriel376@hotmail.com>]

Hi,

I am trying to understand the variable 'icomplete-in-buffer' in
lisp/icomplete.el.

It's a defvar, but users continues to set this variable. I believe it's
due to a lack of documentation or due to a lack of double-dash to mark
it as internal. Some examples:

[1] https://www.reddit.com/r/emacs/comments/fswt7c/using_icomplete_vertically/
[2] https://www.reddit.com/r/emacs/comments/ftq4pq/making_icomplete_more_modern/
[3] https://emacs.stackexchange.com/questions/63340/disable-icomplete-with-emacs-find-file

The bug bug#41805 was opened because of this problem, and closed because
it was a defvar, but there was no clarification regarding the use of
this variable.

Looking at the code, it was introduced in commit 504a03813b (8 years
ago). There are only two references for this variable in the emacs
source tree in the original commit and today: 1) the variable
declaration with a nil value and 2) a condition on 'icomplete-mode' to
add the the function 'icomplete--in-region-setup' to hook
'completion-in-region-mode-hook'. I could not find any external package
that uses this variable.

I tried many approaches to use this variable in combination with
'completion-at-point', but in all cases I got either no results or a
hook error.

Any help is welcome.

Regards,
Gabriel