From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Changes in revision 114466 Date: Mon, 30 Sep 2013 08:05:04 -0700 (PDT) Message-ID: <4af8d59a-d39a-4731-85d9-86fa2f01b5fa@default> References: <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org> <87ioxk3x9z.fsf@zigzag.favinet> <8c8eb64b-74ca-4fba-bb35-a799582423da@default> <87txh24n7d.fsf@rosalinde.fritz.box> 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 1380553556 3031 80.91.229.3 (30 Sep 2013 15:05:56 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 30 Sep 2013 15:05:56 +0000 (UTC) Cc: Xue Fuqiao , Thien-Thi Nguyen , emacs-devel To: Stephen Berman Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Sep 30 17:05:58 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 1VQf2s-0000VO-1T for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 17:05:58 +0200 Original-Received: from localhost ([::1]:49141 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQf2r-0005JA-In for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 11:05:57 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46655) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQf2V-0005I9-7t for emacs-devel@gnu.org; Mon, 30 Sep 2013 11:05:54 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQf2K-00043x-Kk for emacs-devel@gnu.org; Mon, 30 Sep 2013 11:05:35 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:39835) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQf2A-0003zK-UW; Mon, 30 Sep 2013 11:05:15 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r8UF58GN030605 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 30 Sep 2013 15:05:08 GMT Original-Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r8UF57lB010385 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 30 Sep 2013 15:05:08 GMT Original-Received: from abhmt117.oracle.com (abhmt117.oracle.com [141.146.116.69]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r8UF57iQ025612; Mon, 30 Sep 2013 15:05:07 GMT In-Reply-To: <87txh24n7d.fsf@rosalinde.fritz.box> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 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:163729 Archived-At: > This suggests that developers who use them should be working on the > package they are in, hence reading and using the code and commentary of > that package. Yes, so? Having code does not preclude having comments. Having comments does not preclude having documentation. > In contrast, documentation for developers is, I think, > aimed at explaining the code's public interface to use in developing > other packages, not its private, internal only interface Not in Emacs source code, IMHO - it should not be limited to that. Not in dynamic, accessible code that users and developers of all sorts are invited to customize, develop, extend, or do whatever they want with. But anyone can make code as unclear as you like, and likewise to skip commenting or skip documenting code... >From my point of view: add a doc string at the outset. You can then take extra time later to ponder carefully whether it might be OK to remove the doc string, if you really want to do that. As opposed to lazily skipping doc strings to begin with and - maybe - thinking later whether it might not be helpful to add a doc string. Think first of others who might use the code, and that includes "internal" maintainers. It can even include yourself at a later date. > (at least the documentation in the manual; such functions/variables > could have doc strings). We agree. Most functions, variables, widgets, faces,... are *not* documented explicitly in the manuals. And that's as it should be. My (likely lone) opinion remains that there is rarely a good reason to skip adding a doc string. And when there is, pondering whether to do that should come afterward - careful reflection, as opposed to immediately skipping it, as a knee-jerk reaction, just because something has `--' in its name or whatever. It is a false economy to skip adding a doc string. Among other things, trying to describe succinctly what something is or does can sometimes lead one to see that it is in fact not well designed/defined, and could benefit from, e.g, split up, etc. If you cannot describe it simply, that can be a sign that there is room for improvement in the code/design. Just one opinion. =20