From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.bugs Subject: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 18:56:07 +0200 Message-ID: References: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1310753424 449 80.91.229.12 (15 Jul 2011 18:10:24 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 15 Jul 2011 18:10:24 +0000 (UTC) Cc: Lars Magne Ingebrigtsen , 8682@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 15 20:10:20 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QhmqB-0001yl-K0 for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 20:10:19 +0200 Original-Received: from localhost ([::1]:35729 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhmqA-0000Sy-Ky for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 14:10:18 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:55409) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhlhL-0004Pa-So for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 12:57:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QhlhH-0008P6-HM for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 12:57:07 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:51224) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhlhH-0008P1-A0 for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 12:57:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QhlhG-0002Ls-Hv; Fri, 15 Jul 2011 12:57:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Juanma Barranquero Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 15 Jul 2011 16:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8682 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 8682-submit@debbugs.gnu.org id=B8682.13107490169023 (code B ref 8682); Fri, 15 Jul 2011 16:57:02 +0000 Original-Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 16:56:56 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhlh9-0002LU-9I for submit@debbugs.gnu.org; Fri, 15 Jul 2011 12:56:55 -0400 Original-Received: from mail-pz0-f41.google.com ([209.85.210.41]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhlh7-0002LI-9d for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 12:56:53 -0400 Original-Received: by pzk4 with SMTP id 4so1638867pzk.0 for <8682@debbugs.gnu.org>; Fri, 15 Jul 2011 09:56:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:content-transfer-encoding; bh=1G2DF81odljUi6NpybEmZ8hGjinIHBPVxCu+LGlhiOI=; b=wD53hCaWrOk8btDfkd+2OCegHfpBkYRnB5iBIC2bkukU8n1h0/7ixOX2OHozSLhH2s ASXhKq1kuBUMhE/H7q0hpopQqtQpZev9aMh3BLDLw+uQ+sFkufy0xzq2H9P0rvEWVz/8 f/hi15TglSFy4n64Tp6O3kvpguHreNenH2Ick= Original-Received: by 10.142.234.3 with SMTP id g3mr1556348wfh.423.1310749007157; Fri, 15 Jul 2011 09:56:47 -0700 (PDT) Original-Received: by 10.142.144.4 with HTTP; Fri, 15 Jul 2011 09:56:07 -0700 (PDT) In-Reply-To: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 15 Jul 2011 12:57:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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:49194 Archived-At: On Fri, Jul 15, 2011 at 17:06, Drew Adams wrote: > "Internal" functions too deserve doc strings, in general. > > And nothing in Emacs is truly "internal". =C2=A0Emacs purposefully docume= nts itself, > at all levels. =C2=A0That documentation is available to all users interac= tively. Of course there are internal elisp functions. Many of them even use a convention of having two consecutive dashes in the name to mark that they are internal, but not all. And what makes them internal is that they are an implementation detail and could be removed, or changed beyond all recognition, at any moment. Documenting them past the simple "This is an internal function" leads the user-developer to falsely believe that they are part of the interface, but they are not. Otherwise, nothing could ever be changed but painstakingly and with lot of ugly compatibility code. Which is fine for the advertised interfaces, but not for every single function in every single package in lisp/**/*.el. First someone asks to document them all, then s/he will use them in some package, and finally s/he will complain harshly when they are deleted in some future release. Better to say clearly: don't do that, or do it under you own responsability, after looking at the code, and knowing full well that if you do you'll likely need to workaround changes in the future. (I'm not talking about the specific changes in this bug thread, but comments like "Nothing in Emacs is truly 'internal'" cannot be let pass unchallenged...) =C2=A0 =C2=A0 Juanma