Subject: RE: bug#8795: 24.0.50; `completion-try-completion' addition of METADATA arg

From: "Drew Adams" <[email-masked]>
Date: Wed, 12 Oct 2011 15:09:02 -0700

> > Still no doc for arg METADATA.
> 
> Indeed.  I have no intention to add any doc for it.
> It's obvious from context, and this is an internal function.

The bug should not be closed as fixed/done.  "Wontfix" is what you are saying.

And it is clearly not internal.  If it were internal then you would not have
needed to change METADATA to `&optional'.  And I was not the only one to point
out that its not being optional broke backward compatibility.

http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00327.html
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00348.html

I use it in my code, and obviously others do too.  IIRC, it was you who
suggested that I use it instead of `try-completion', at least in some contexts
(or possibly it was c*-all-c* vs all-c*, or both - anyway, I use both). [*]

Its parameters, including METADATA, should be documented.  And no, it is not at
all "obvious from context" what could or should be passed as METADATA, and when.
The meaning and behavior should be described.  Is that so hard to do?

----
[*] I use it in code such as this (similar, for c*-all-c*):
(when (consp filtered-candidates)
  (let ((common-prefix
         (if (icicle-not-basic-prefix-completion-p)
             (icicle-completion-try-completion ; <=========
              input minibuffer-completion-table
              minibuffer-completion-predicate
              (length input)
              (and (fboundp 'completion--field-metadata)
                   (completion--field-metadata ; Emacs 24
                    (field-beginning))))
           (try-completion input minibuffer-completion-table
                           minibuffer-completion-predicate))))
    (setq icicle-common-match-string
          (if (eq t common-prefix) input common-prefix))))

`icicle-c*-try-c*' is nearly the same as `c*-try-c*', but with bug #4708 fixed
(so it returns nil when there is no such file etc.)

(defun icicle-completion-try-completion (string table pred point
                                         &optional metadata)
  "Icicles version of `completion-try-completion'.
1. Handle all Emacs versions.
2. Remove the last cdr, which might hold the base size.
3. METADATA is optional and defaults to `completion--field-metadata'
   at `field-beginning'."
  (let* ((mdata  (and (fboundp 'completion--field-metadata)
                      (or metadata
                          (completion--field-metadata
                           (field-beginning)))))
         (res    (if (fboundp 'completion--field-metadata)
                     (completion-try-completion ; <=========
                      string table pred point mdata)
                   (completion-try-completion   ; <=========
                    string table pred point))))
    (when (consp res) (setq res  (car res)))
    res))

If I can easily simplify some of this I would be glad to hear how.