From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@russet.org.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality. Date: Thu, 03 Dec 2015 17:34:54 +0000 Message-ID: <87si3jo2pt.fsf@russet.org.uk> References: <83oaeaj5la.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1449164132 10276 80.91.229.3 (3 Dec 2015 17:35:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 3 Dec 2015 17:35:32 +0000 (UTC) Cc: Phillip Lord , emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 03 18:35:28 2015 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 1a4Xmu-0000jj-TQ for ged-emacs-devel@m.gmane.org; Thu, 03 Dec 2015 18:35:25 +0100 Original-Received: from localhost ([::1]:36683 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a4Xmt-00080H-RT for ged-emacs-devel@m.gmane.org; Thu, 03 Dec 2015 12:35:23 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58670) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a4Xme-0007wi-9K for emacs-devel@gnu.org; Thu, 03 Dec 2015 12:35:13 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a4XmY-0003eL-Mq for emacs-devel@gnu.org; Thu, 03 Dec 2015 12:35:08 -0500 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:58377) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a4XmR-0003cX-KL; Thu, 03 Dec 2015 12:34:55 -0500 Original-Received: from smtpauth-vm.ncl.ac.uk ([10.8.233.129] helo=smtpauth.ncl.ac.uk) by cheviot22.ncl.ac.uk with esmtp (Exim 4.63) (envelope-from ) id 1a4XmQ-0005yp-FY; Thu, 03 Dec 2015 17:34:54 +0000 Original-Received: from jangai.ncl.ac.uk ([10.66.67.223] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1a4XmQ-0005cO-OQ; Thu, 03 Dec 2015 17:34:54 +0000 In-Reply-To: (John Wiegley's message of "Thu, 3 Dec 2015 10:54:17 -0500") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 128.240.234.22 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:195820 Archived-At: John Wiegley writes: > <#secure method=pgpmime mode=sign> >>>>>> Eli Zaretskii writes: > >> This commit documents internal functions and variables. IMO, if we think >> they deserve being documented (and I think I agree), they shouldn't be >> internal in the first place. > > If they're truly internal, I don't think they should be documented in > elisp.texi. Sufficient documentation is provided for such functions via the > docstring. > > If one feels they do belong in elisp.texi, they shouldn't be internal, as Eli > indicates. > > In a sense, elisp.texi defines our "Emacs Lisp API" to programmers, so > anything we document there represent a certain level of commitment. Yeah, think that's true. I made them internal but then when I was writing the documentation thought perhaps they should be documented. Deciding what is "end-user" functionality and what is "implementation" gets a bit hard when you are talking about code of this form. I'll patch them up and make these two non internal. Phil