From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#24627: "internal" designation [was: bug#24627: 24.5; (thing-at-point 'list) ...] Date: Tue, 11 Oct 2016 10:16:30 -0700 (PDT) Message-ID: <664b1d26-9a9e-4294-a216-d1a26f792927@default> References: <48df5626-be32-ffb0-55f5-1b6f116a6940@easy-emacs.de> <87fuo3r1p0.fsf@gmail.com> <08d6c55e-f060-fabc-5657-2e80a1d06ab0@easy-emacs.de> <878ttu97e3.fsf@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1476206254 6022 195.159.176.226 (11 Oct 2016 17:17:34 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 11 Oct 2016 17:17:34 +0000 (UTC) Cc: 24627@debbugs.gnu.org To: Tino Calancha , Andreas =?UTF-8?Q?R=C3=B6hler?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Oct 11 19:17:30 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bu0g4-0008H3-KY for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Oct 2016 19:17:20 +0200 Original-Received: from localhost ([::1]:57124 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bu0g2-0007ra-B8 for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Oct 2016 13:17:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35943) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bu0fs-0007qb-1z for bug-gnu-emacs@gnu.org; Tue, 11 Oct 2016 13:17:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bu0fl-00070J-VN for bug-gnu-emacs@gnu.org; Tue, 11 Oct 2016 13:17:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46203) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bu0fl-00070F-RN for bug-gnu-emacs@gnu.org; Tue, 11 Oct 2016 13:17:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bu0fl-0007Gm-Nh for bug-gnu-emacs@gnu.org; Tue, 11 Oct 2016 13:17:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 11 Oct 2016 17:17:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24627 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24627-submit@debbugs.gnu.org id=B24627.147620620527917 (code B ref 24627); Tue, 11 Oct 2016 17:17:01 +0000 Original-Received: (at 24627) by debbugs.gnu.org; 11 Oct 2016 17:16:45 +0000 Original-Received: from localhost ([127.0.0.1]:52393 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bu0fU-0007GD-Q3 for submit@debbugs.gnu.org; Tue, 11 Oct 2016 13:16:45 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:22896) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bu0fT-0007Fx-5N for 24627@debbugs.gnu.org; Tue, 11 Oct 2016 13:16:43 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u9BHGYPE013379 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 11 Oct 2016 17:16:35 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0021.oracle.com (8.13.8/8.14.4) with ESMTP id u9BHGXaE013392 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 11 Oct 2016 17:16:34 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id u9BHGV16031293; Tue, 11 Oct 2016 17:16:32 GMT In-Reply-To: <878ttu97e3.fsf@gmail.com> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:124356 Archived-At: > (defun thing-at-point-bounds-of-list-at-point () > "Return the bounds of the list at point. > -[Internal function used by `bounds-of-thing-at-point'.]" > +\[Internal function used by `bounds-of-thing-at-point'.\]" FWIW: I object to such an "internal" designation being in that doc string. What's the point of that? What makes this function particularly "internal"? Seems like a gratuitous characterization (at best). That the function is used by `bounds-of-thing-at-point' is obvious, and anyway that fact does not belong in its doc string. IMHO, there is too much of this trying to wall off this or that as beomg in some sense "internal" (with no explanation, including no code comment, as to what makes it internal). The definition typically given for this characterization is that the thing so designated is _liable to change_. Big deal - lots of stuff is liable to change. Saying that doesn't help anyone. How liable? Why liable? And when such a thing does change, it is likely that other things, not designated as "internal" also change, including user-visible behavior. IOW, the thing walled off is often not really internal at all - the code is not just one implementation of a given (stable, non-internal) interface. Typically, there is nothing special or tentative about the code. Emacs and Emacs Lisp are things that invite users to dig into and change them. Emacs is not your typical software use and development. (Likewise, free software, BTW: there is no solid separation between user and developer.) For Emacs, this "internal" designation is generally a useless crutch, IMO. And my impression is that recently (the last several years) its use has been spread much more. In the more distant past it was very rarely resorted to, if at all. And I don't think anyone suffered from its lack of use. No one needed to be warned that this or that might change. My sense is that this has been used more and more simply as a way of warding off users from offering suggestions about the thing that is so "protected", whether it be requesting better doc or something else. My estimation of the "internal" label contagion is this: from useless to nefarious. It seems unemacsy, trying to put an unnecessary wall between Emacs development and Emacs users. There should be little or no reason for Emacs to tell users "don't use this". Removing the "internal" nonsense for this function would be a start...