GNU bug report logs - #18636
24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME?

Previous Next

Full log

Message #31 received at 18636 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 18636 <at> debbugs.gnu.org
Subject: RE: bug#18636: 24.4.50;	doc of `display-monitor-attributes-list' -
 DISPLAY? FRAME?
Date: Wed, 8 Oct 2014 07:04:51 -0700 (PDT)

> > > > And it should call out the
> > > > relation between the two.  For example, if a frame is passed
> > > > and its display is used (= its `display' frame parameter),
> > > > then say so.
> > >
> > > That's not what happens, though.  Each function extracts the
> > > info it needs from whatever kind of argument it is passed, and
> > > then uses that info.
> >
> > I said, "For example". Whatever the actual relation between the
> > two is, it should be described.  (Descriptions like "the
> > information it needs" and "that info" are OK for here, but would
> > not be helpful in the doc string.)
> 
> I'm not sure what you think the documentation should tell about
> this, and why.  Each function needs something different from its argument;
> surely, describing all that in the doc string is counter-productive.
> Whoever needs those details, should read the code.
> 
> IOW, what other details are required to correctly invoke and use
> these functions?

Dunno what other details are needed to understand these functions.
That was the point.

I'm not looking for implementation details.  I'm guessing that a
description of the function, and a good understanding of it, involves
some description/understanding of the argument and what it means
to the function.  What the function needs it for - not in terms of
just what it does with it, but in logical terms - why it is required.

Maybe no more info is needed - dunno.  But usually a user can tell
why a given argument might have a value of different types, e.g. a
buffer or a string that names a buffer.  The connection here, between
a frame arg value and a display arg value, is not obvious.  I was
guessing that what the function needs, ultimately, is a display, and
that if given a frame it uses the frame's display.  But apparently 
that is not the connection.

I'm in the dark on this.  Use your own judgment.  If you think
nothing is unclear or missing, that's good enough for me.

Previous Next

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