From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.devel Subject: RE: Changes in revision 114466 Date: Tue, 01 Oct 2013 11:11:23 +0900 Message-ID: <87zjqtkaes.fsf@uwakimon.sk.tsukuba.ac.jp> References: <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org> <87ioxk3x9z.fsf@zigzag.favinet> <8c8eb64b-74ca-4fba-bb35-a799582423da@default> <87txh24n7d.fsf@rosalinde.fritz.box> <4af8d59a-d39a-4731-85d9-86fa2f01b5fa@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Trace: ger.gmane.org 1380593512 24703 80.91.229.3 (1 Oct 2013 02:11:52 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 1 Oct 2013 02:11:52 +0000 (UTC) Cc: Xue Fuqiao , Thien-Thi Nguyen , Stephen Berman , emacs-devel To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 01 04:11:54 2013 Return-path: Envelope-to: ged-emacs-devel@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 1VQpRK-0008UR-2T for ged-emacs-devel@m.gmane.org; Tue, 01 Oct 2013 04:11:54 +0200 Original-Received: from localhost ([::1]:52370 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQpRJ-0006Vb-Ke for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 22:11:53 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52182) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQpR9-0006VH-Cf for emacs-devel@gnu.org; Mon, 30 Sep 2013 22:11:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQpQy-0006Ib-Gu for emacs-devel@gnu.org; Mon, 30 Sep 2013 22:11:43 -0400 Original-Received: from mgmt2.sk.tsukuba.ac.jp ([130.158.97.224]:48448) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQpQy-00062e-6N; Mon, 30 Sep 2013 22:11:32 -0400 Original-Received: from uwakimon.sk.tsukuba.ac.jp (uwakimon.sk.tsukuba.ac.jp [130.158.99.156]) by mgmt2.sk.tsukuba.ac.jp (Postfix) with ESMTP id 513A4970A1C; Tue, 1 Oct 2013 11:11:24 +0900 (JST) Original-Received: by uwakimon.sk.tsukuba.ac.jp (Postfix, from userid 1000) id 15C621205A7; Tue, 1 Oct 2013 11:11:24 +0900 (JST) In-Reply-To: <4af8d59a-d39a-4731-85d9-86fa2f01b5fa@default> X-Mailer: VM undefined under 21.5 (beta33) "horseradish" f478c6c7528c+ XEmacs Lucid (x86_64-unknown-linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 130.158.97.224 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163757 Archived-At: Drew Adams writes: > My (likely lone) opinion remains that there is rarely a good reason > to skip adding a doc string. In this wide world you're not alone. XEmacs policy has historically been to put docstrings in everything that's "def'd" except for one- line defsubsts and the like. We also systematically convert leading comments (and often comments where a docstring would go) to docstrings more or less systematically. On the other hand, many people (and the Emacs project, I believe) have a policy of "docstrings document the API, if you want to know what it's for or how it works, read the manual". With good naming of functions and parameters, often there is no need for a separate description of the API. Then the argument is that if you're going to critically read the code anyway, the docstring means less lines of code on screen. I think you lose here on the basis that this is, pretty much, Emacs policy.