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#957: 23.0.60; No doc string for Dired functions Date: Wed, 6 Jul 2011 12:16:37 -0700 Message-ID: References: <001d01c91360$8a9cf4a0$c2b22382@us.oracle.com> 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 1309983639 8573 80.91.229.12 (6 Jul 2011 20:20:39 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 6 Jul 2011 20:20:39 +0000 (UTC) Cc: 957@debbugs.gnu.org To: "'Lars Magne Ingebrigtsen'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jul 06 22:20:35 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 1QeYaG-00058U-KS for geb-bug-gnu-emacs@m.gmane.org; Wed, 06 Jul 2011 22:20:32 +0200 Original-Received: from localhost ([::1]:46301 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QeYaF-0007yB-Fl for geb-bug-gnu-emacs@m.gmane.org; Wed, 06 Jul 2011 16:20:31 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:58367) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QeXas-0006hU-DQ for bug-gnu-emacs@gnu.org; Wed, 06 Jul 2011 15:17:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QeXap-0006PI-IE for bug-gnu-emacs@gnu.org; Wed, 06 Jul 2011 15:17:06 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:58724) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QeXap-0006P6-6G for bug-gnu-emacs@gnu.org; Wed, 06 Jul 2011 15:17:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QeXao-00037h-Gg; Wed, 06 Jul 2011 15:17: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: Wed, 06 Jul 2011 19:17:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 957 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 957-submit@debbugs.gnu.org id=B957.130997981611982 (code B ref 957); Wed, 06 Jul 2011 19:17:02 +0000 Original-Received: (at 957) by debbugs.gnu.org; 6 Jul 2011 19:16: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 1QeXai-00037D-5W for submit@debbugs.gnu.org; Wed, 06 Jul 2011 15:16:56 -0400 Original-Received: from rcsinet15.oracle.com ([148.87.113.117]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QeXag-00036x-9G for 957@debbugs.gnu.org; Wed, 06 Jul 2011 15:16:55 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by rcsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p66JGkll025814 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 6 Jul 2011 19:16:47 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p66JGj8K006604 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 6 Jul 2011 19:16:45 GMT Original-Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p66JGdK3031326; Wed, 6 Jul 2011 14:16:39 -0500 Original-Received: from dradamslap1 (/10.159.55.239) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 06 Jul 2011 12:16:39 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 Thread-Index: Acw8C5sEmlowcnpCQPSreenChfxzIwABD59w X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4E14B4A0.0059: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: Wed, 06 Jul 2011 15:17: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:48123 Archived-At: > > There is still no doc string for many useful Dired functions, from > > things like `dired-repeat-overlines' to all of the tree Dired > > non-interactive functions. At a minimum, the arguments should be > > described in a doc string. Even some commands, like > > `dired-kill-line', still have no doc. > > I've added a doc to `dired-kill-line' Thank you. > but I don't know what `dired-repeat-overlines' is... All the more reason for it to get a doc string! You don't know what it is, but _it_ should know what it is and be able to tell us. Someone (TM) will need to figure that out and give it a little help in the self-explanation department. > And the noninteractive functions don't need doc strings, > really, do they? Sure they do, in general. Since when do we document only commands? In the Dark Ages, doc strings were relatively more expensive (disk, memory, etc.), and some minor functions were handled with only a comment. Nowadays there is rarely a good reason not to provide a doc string. Emacs is the self-documenting editor. If you must access the source code just to get a description of a function from comments, or worse, to parse uncommented code to figure out what a function does, then Emacs is not doing its self-documenting job well.