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#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 08:06:06 -0700 Message-ID: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1310745814 17263 80.91.229.12 (15 Jul 2011 16:03:34 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 15 Jul 2011 16:03:34 +0000 (UTC) Cc: 8682@debbugs.gnu.org To: "'Lars Magne Ingebrigtsen'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 15 18:03:30 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 1QhkrP-0006dB-Si for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 18:03:28 +0200 Original-Received: from localhost ([::1]:47474 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhkrP-0005MG-1t for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 12:03:27 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:39771) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qhjyq-0005TD-Ek for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:07:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Qhjyo-0005Dq-Rz for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:07:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:37412) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qhjyo-0005Dm-Ip for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 11:07:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1Qhjyo-0004gO-12; Fri, 15 Jul 2011 11:07:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" 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 15:07:01 +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.131074238317950 (code B ref 8682); Fri, 15 Jul 2011 15:07:01 +0000 Original-Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 15:06:23 +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 1QhjyA-0004fT-5b for submit@debbugs.gnu.org; Fri, 15 Jul 2011 11:06:22 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qhjy8-0004fH-An for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 11:06:20 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6FF6C1S029409 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 15 Jul 2011 15:06:14 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6FF6CsG028723 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 15 Jul 2011 15:06:12 GMT Original-Received: from abhmt118.oracle.com (abhmt118.oracle.com [141.146.116.70]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6FF66Ka015643; Fri, 15 Jul 2011 10:06:06 -0500 Original-Received: from dradamslap1 (/10.159.34.212) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 08:06:06 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcxC9c4nkxmAmpzmRgu/9YUawys6FwACWh6Q X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090209.4E205766.00B9:SCFMA922111,ss=1,re=-4.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 15 Jul 2011 11:07: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:49156 Archived-At: > It's an internal function. "Internal" functions too deserve doc strings, in general. And nothing in Emacs is truly "internal". Emacs purposefully documents itself, at all levels. That documentation is available to all users interactively. Skip creating reasonable doc strings and you stab Emacs, the "self-documenting editor", in the back. It was only in the Dark Ages, when doc strings were expensive because hardware was expensive, that we used comments instead of doc strings for many "internal" functions. We should not be lazy and cop out wrt "internal" functions. There is no strict separation in Emacs (or GNU generally) between users and developers, between "internal" code and external use of that code. > The only thing that's useful in that doc string is the thing that's > already there, and which you want removed: > > > And you can remove this sentence from the doc string - a > > function's doc should, in general, not mention callers: > > "It is called by the function `isearch-forward' and other related > > functions." No, that is not "useful". More importantly, it is generally a bad idea for a callee to call out who calls it. There are exceptional cases, but this is not one.