From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#18636: 24.4.50; doc of `display-monitor-attributes-list' - DISPLAY? FRAME? Date: Wed, 8 Oct 2014 07:04:51 -0700 (PDT) Message-ID: References: <<2cb10ab0-7eb3-43a8-9fc2-72374602b55f@default>> <<83oatmkgfy.fsf@gnu.org>> <<986f56fa-af7e-4843-a0fa-047b2f49fb18@default>> <<83a956k7pl.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1412777134 10543 80.91.229.3 (8 Oct 2014 14:05:34 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 8 Oct 2014 14:05:34 +0000 (UTC) Cc: 18636@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Oct 08 16:05:26 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xbrrn-0004zn-8h for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 Oct 2014 16:05:23 +0200 Original-Received: from localhost ([::1]:36401 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xbrrm-0005xV-SX for geb-bug-gnu-emacs@m.gmane.org; Wed, 08 Oct 2014 10:05:22 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38931) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xbrrb-0005xG-Cn for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 10:05:20 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XbrrS-0002Jy-Mk for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 10:05:11 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:46576) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XbrrS-0002Js-Jl for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 10:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1XbrrS-0008Lj-7G for bug-gnu-emacs@gnu.org; Wed, 08 Oct 2014 10:05:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 Oct 2014 14:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 18636 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 18636-submit@debbugs.gnu.org id=B18636.141277710132085 (code B ref 18636); Wed, 08 Oct 2014 14:05:02 +0000 Original-Received: (at 18636) by debbugs.gnu.org; 8 Oct 2014 14:05:01 +0000 Original-Received: from localhost ([127.0.0.1]:38140 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XbrrP-0008LQ-TX for submit@debbugs.gnu.org; Wed, 08 Oct 2014 10:05:00 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:17087) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XbrrN-0008LH-Jc for 18636@debbugs.gnu.org; Wed, 08 Oct 2014 10:04:58 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s98E4ts3013435 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 8 Oct 2014 14:04:56 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s98E4q32018892 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 8 Oct 2014 14:04:54 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id s98E4pKc018268; Wed, 8 Oct 2014 14:04:52 GMT In-Reply-To: <<83a956k7pl.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:94300 > > > > And it should call out the > > > > relation between the two. For example, if a frame is passed > > > > and its display is used (=3D 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.) >=20 > 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. >=20 > 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=20 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.