From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Berman Newsgroups: gmane.emacs.devel Subject: Re: Changes in revision 114466 Date: Mon, 30 Sep 2013 12:29:26 +0200 Message-ID: <87txh24n7d.fsf@rosalinde.fritz.box> References: <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org> <87ioxk3x9z.fsf@zigzag.favinet> <8c8eb64b-74ca-4fba-bb35-a799582423da@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1380536980 31403 80.91.229.3 (30 Sep 2013 10:29:40 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 30 Sep 2013 10:29:40 +0000 (UTC) Cc: Xue Fuqiao , Thien-Thi Nguyen , emacs-devel To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Sep 30 12:29:43 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 1VQajW-00036h-Qd for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 12:29:42 +0200 Original-Received: from localhost ([::1]:48027 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQajW-00035h-A4 for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 06:29:42 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47212) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQajP-00035W-2Y for emacs-devel@gnu.org; Mon, 30 Sep 2013 06:29:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQajK-0003Wr-72 for emacs-devel@gnu.org; Mon, 30 Sep 2013 06:29:35 -0400 Original-Received: from mout.gmx.net ([212.227.15.19]:53714) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQajJ-0003Wd-UA for emacs-devel@gnu.org; Mon, 30 Sep 2013 06:29:30 -0400 Original-Received: from rosalinde.fritz.box ([89.245.71.186]) by mail.gmx.com (mrgmx102) with ESMTPSA (Nemesis) id 0MMHaL-1VTc4Z3bht-007zTy for ; Mon, 30 Sep 2013 12:29:27 +0200 In-Reply-To: <8c8eb64b-74ca-4fba-bb35-a799582423da@default> (Drew Adams's message of "Sun, 29 Sep 2013 22:21:18 -0700 (PDT)") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) X-Provags-ID: V03:K0:+p7P6tE37RxgPnNolyxPzyi2lfG4pOLoOR7oJkG+28mAMGqDlIU zGNcQRoZ/aYdkYdIp1ggmEYNn0043pal7HKkSeVga3K+3mf9Zq0ws2oeChWk1VXvYwccxKc S77oKN9RxCnk/Nt6bZ04STqTZS/honWhOxW3bjUN6avFRRV3b9iiD/IU0S7751EHaVxHl/T 10j9PnPwZRal3I+vot0Iw== X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 212.227.15.19 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:163724 Archived-At: On Sun, 29 Sep 2013 22:21:18 -0700 (PDT) Drew Adams wrote: >> But I see one problem: not every {functions, variables, ...} needs >> documenting. E.g., some functions/variables use two hyphens to separate >> prefix. These functions/variables usually don't needs documenting. > > Why not? Do you think developers do not need documentation? According to Stefan Monnier (see http://lists.gnu.org/archive/html/emacs-devel/2013-06/msg01129.html): [These functions/variables are] not meant to be used by other packages [, which] means that something defined with "--" can completely change (or disappear) from one release to the other. 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. 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 (at least the documentation in the manual; such functions/variables could have doc strings). Steve Berman