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#14843: 24.3.50; `line-move', `line-move-visual' need doc strings Date: Thu, 11 Jul 2013 13:52:23 -0700 (PDT) Message-ID: <83e00f63-4458-4901-8816-4875f599d9cc@default> References: <<43758336-46c0-42cf-a16d-6412c5e003d8@default>> <<83r4f46hmm.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 1373575988 27000 80.91.229.3 (11 Jul 2013 20:53:08 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 11 Jul 2013 20:53:08 +0000 (UTC) Cc: 14843@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 11 22:53:08 2013 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 1UxNrP-0004Lj-JW for geb-bug-gnu-emacs@m.gmane.org; Thu, 11 Jul 2013 22:53:07 +0200 Original-Received: from localhost ([::1]:36493 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UxNrP-0000G8-9N for geb-bug-gnu-emacs@m.gmane.org; Thu, 11 Jul 2013 16:53:07 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53388) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UxNrL-0000FW-D8 for bug-gnu-emacs@gnu.org; Thu, 11 Jul 2013 16:53:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UxNrK-0005ht-By for bug-gnu-emacs@gnu.org; Thu, 11 Jul 2013 16:53:03 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:54225) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UxNrK-0005hp-8N for bug-gnu-emacs@gnu.org; Thu, 11 Jul 2013 16:53:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1UxNrJ-0003k9-QM for bug-gnu-emacs@gnu.org; Thu, 11 Jul 2013 16:53: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: Thu, 11 Jul 2013 20:53:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 14843 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 14843-submit@debbugs.gnu.org id=B14843.137357595514347 (code B ref 14843); Thu, 11 Jul 2013 20:53:01 +0000 Original-Received: (at 14843) by debbugs.gnu.org; 11 Jul 2013 20:52:35 +0000 Original-Received: from localhost ([127.0.0.1]:48540 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1UxNqs-0003jL-Kn for submit@debbugs.gnu.org; Thu, 11 Jul 2013 16:52:34 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:49117) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1UxNqq-0003ir-1p for 14843@debbugs.gnu.org; Thu, 11 Jul 2013 16:52:32 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r6BKqPDI004124 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 11 Jul 2013 20:52:25 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6BKqObM001480 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 11 Jul 2013 20:52:25 GMT Original-Received: from abhmt109.oracle.com (abhmt109.oracle.com [141.146.116.61]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6BKqOsR010536; Thu, 11 Jul 2013 20:52:24 GMT In-Reply-To: <<83r4f46hmm.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.7 (607090) [OL 12.0.6668.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:76248 Archived-At: > > > > These functions, especially `line-move', are used all over the plac= e. > > > > They need doc strings, with complete descriptions of their paramete= rs. > > > > > > They are internal functions. Under what circumstances did you need t= o > > > use them directly? Why wasn't next/previous-line enough? > > > > Read what I wrote: they "are used all over the place". In the Emacs co= de > > alone, not to mention in 3rd-party code. They are not "internal" to > > simple.el. They are not internal to anything. Reality. >=20 > That an internal function is used all over the Emacs code is a small > wonder. It just means someone was smart enough to capture a frequent > need of many features. And each person who wrote such Emacs code needed to figure out for herself what the parameters mean (or not bother). Perhaps it is also a small wonder that NONE of the uses of `line-move', including those in simple.el itself, make ANY USE of the additional parameters introduced in Emacs 22 (and not used even in 22). An indication, perhaps, that even Emacs Dev could use a little Emacs self-documenting. Doc strings are for everyone. Arguing not to create clear doc strings for "internal" functions made littl= e sense in the 1960s. It makes no sense at all now. In bygone days, Emacs code had comments instead of doc strings for some functions (sometimes systematically, for a given library). Most of those comments were changed to doc strings once the Dark Ages were over. Look at the large comments preceding these two function defuns. Yet even those elaborate comments do not describe the parameters. Emacs can do better. Much better.