From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Small docstring improvements Date: Sat, 20 Aug 2016 18:34:33 +0300 Message-ID: <83eg5jcv3q.fsf@gnu.org> References: <83shtzdijr.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1471707327 25856 195.159.176.226 (20 Aug 2016 15:35:27 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 20 Aug 2016 15:35:27 +0000 (UTC) Cc: emacs-devel@gnu.org To: Philipp Stephani Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Aug 20 17:35:23 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bb8Is-0006PV-JU for ged-emacs-devel@m.gmane.org; Sat, 20 Aug 2016 17:35:22 +0200 Original-Received: from localhost ([::1]:33493 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bb8Im-00055G-OE for ged-emacs-devel@m.gmane.org; Sat, 20 Aug 2016 11:35:16 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42582) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bb8IF-00055B-Fo for emacs-devel@gnu.org; Sat, 20 Aug 2016 11:34:44 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bb8I9-00070q-IH for emacs-devel@gnu.org; Sat, 20 Aug 2016 11:34:42 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:34344) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bb8I9-00070k-F1; Sat, 20 Aug 2016 11:34:37 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1730 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bb8I6-0007rI-Ou; Sat, 20 Aug 2016 11:34:35 -0400 In-reply-to: (message from Philipp Stephani on Sat, 20 Aug 2016 13:52:03 +0000) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:206699 Archived-At: > From: Philipp Stephani > Date: Sat, 20 Aug 2016 13:52:03 +0000 > Cc: emacs-devel@gnu.org > > > +If START is nil, that means to use the entire buffer contents; END is > > +ignored. > > "the entire accessible portion of the buffer" is more accurate than > "the entire buffer contents", when narrowing is in effect. > > That would be incorrect, as these functions ignore narrowing. You are right, I didn't see that write_region calls widen. Sorry. > > +This does not take narrowing into account; to count the number of > > +characters in the accessible portion of the buffer, use > > +‘(- (point-max) (point-min))’. */) > > The advice in the last sentence doesn't work when BUFFER is non-nil. > (I actually doubt that the advice is needed here; it's enough to have > something like that in the ELisp manual -- which already hints on > that, but maybe we should make that more explicit. > > I'd prefer a bit of redundancy in a very basic function such as this. At least I wouldn't want to search the Elisp > manual for additional information unless really necessary. I'd reword it to "the accessible portion of the current > buffer". If we want to give advice like that, IMO we should also give such an advice for when BUFFER is non-nil.