Re: Doc string and operation of color-distance

[Mark Oteiza <mvoteiza@udel.edu>]

On 15/09/17 at 04:30pm, Eli Zaretskii wrote:
> > Date: Thu, 14 Sep 2017 15:12:26 -0400
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > 
> > On 14/09/17 at 09:45pm, Eli Zaretskii wrote:
> > > Mark, the new color-distance says something strange in its doc string:
> > > 
> > >   (color-distance COLOR1 COLOR2 &optional FRAME METRIC)
> > > 
> > >   Return an integer distance between COLOR1 and COLOR2 on FRAME.
> > >   COLOR1 and COLOR2 may be either strings containing the color name,
> > >   or lists of the form (RED GREEN BLUE), each in the range 0 to 65535 inclusive.
> > >   If FRAME is unspecified or nil, the current frame is used.
> > >   If METRIC is unspecified or nil, a modified L*u*v* metric is used.
> > > 
> > > The last sentence should say "non-nil", I think
> > 
> > No, the 'nil' is correct--if no metric is given as an argument,
> > color_distance is used which, as the comments say, is a modified L*u*v*
> > metric.
> 
> Yes, but the comments also reference the article which describes the
> metric, whereas the doc string doesn't.
> 
> I think we should either leave the nil case alone -- it wasn't
> documented before in such detail -- or add more explanations and
> perhaps the reference.
> 
> What's important is to describe the non-nil case.

OK, I agree.  How about the following?

diff --git a/src/xfaces.c b/src/xfaces.c
index 012de4e7af..b309c16127 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -4093,7 +4093,8 @@ DEFUN ("color-distance", Fcolor_distance, Scolor_distance, 2, 4, 0,
 COLOR1 and COLOR2 may be either strings containing the color name,
 or lists of the form (RED GREEN BLUE), each in the range 0 to 65535 inclusive.
 If FRAME is unspecified or nil, the current frame is used.
-If METRIC is unspecified or nil, a modified L*u*v* metric is used.  */)
+If METRIC is specified, it should be a function that accepts
+two lists of the form (RED GREEN BLUE) aforementioned. */)
   (Lisp_Object color1, Lisp_Object color2, Lisp_Object frame,
    Lisp_Object metric)
 {
@@ -4112,7 +4113,13 @@ If METRIC is unspecified or nil, a modified L*u*v* metric is used.  */)
   if (NILP (metric))
     return make_number (color_distance (&cdef1, &cdef2));
   else
-    return call2 (metric, color1, color2);
+    return call2 (metric,
+                  list3 (make_number (cdef1.red),
+                         make_number (cdef1.green),
+                         make_number (cdef1.blue)),
+                  list3 (make_number (cdef2.red),
+                         make_number (cdef2.green),
+                         make_number (cdef2.blue)));
 }
 
 \f