GNU bug report logs - #8795
24.0.50; `completion-try-completion' addition of METADATA arg

Previous Next

Full log

Message #37 received at 8795-done <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8795-done <at> debbugs.gnu.org
Subject: RE: bug#8795: 24.0.50;
	`completion-try-completion' addition of METADATA arg
Date: Thu, 13 Oct 2011 07:14:58 -0700

> > And it is clearly not internal.
> 
> It is.  "Internal" reflects the intention behind this 
> function.  As the author of the code, I know better than
> you do whether it's internal or not.

Your intention is one thing.  Reality (actual use) is apparently another.

You already acknowledged that you didn't think anyone would ever use this - you
were surprised that people do (have to?).  What you intended as internal, not
realizing the impact of your changes, is not internal - in practice.

Do you think people jump through hoops like this just because they want to
complicate things, with different code for different Emacs versions?

;; Recent Emacs
(completion-try-completion
  input minibuffer-completion-table
  minibuffer-completion-predicate
  (length input)
  (completion--field-metadata (field-beginning)))

instead of just

;; Older Emacs
(try-completion input minibuffer-completion-table
                minibuffer-completion-predicate))

How much simpler it would be to just use `try-completion' here for all Emacs
versions. 

As I said, "If I can easily simplify some of this I would be glad to hear how."
No one _wants_ to use something you intended as internal, if they don't have to.

> > 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.
> 
> Oh, so because I was nice enough to go through the trouble to preserve
> backward compatibility, I am now bound to additionally document
> the obvious because you don't find it obvious enough?

Backward compatibility takes care of, well, backward compatibility.  It does not
take care of documenting how to use the new (more complex) paraphernalia.

Again, why not?  Is it so hard to explain the meaning and behavior of the
METADATA parameter?  What's wrong with describing even an "internal" function?
If you so strongly resist putting the info in a doc string, then put it in a
code comment, at least.  Code comments are how we document "internal" functions,
no?

Whether something like this is obvious enough is not for you to determine, but
for readers of the code.  An author can vouch for the author's _intention_, but
not for how well the meaning and behavior are communicated.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.