Eli Zaretskii <eliz@gnu.org> schrieb am Sa., 20. Aug. 2016 um 09:08 Uhr:

> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Fri, 19 Aug 2016 19:26:14 +0000
> >
> > here's a patch that clarifies some docstrings a bit. Please take a look.
> I'll push to master if this is OK.
>
> Some comments below.  Please push to emacs-25, not to master, as this
> is just a documentation change, and there's no reason to delay it
> until after 25.1.
>

Thanks.


>
> > +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.


>
> > --- a/src/editfns.c
> > +++ b/src/editfns.c
> > @@ -1065,7 +1065,12 @@ usage: (save-current-buffer &rest BODY)  */)
> >
> >  DEFUN ("buffer-size", Fbuffer_size, Sbuffer_size, 0, 1, 0,
> >         doc: /* Return the number of characters in the current buffer.
> > -If BUFFER, return the number of characters in that buffer instead.  */)
> > +If BUFFER is not nil, return the number of characters in that buffer
> > +instead.
> > +
> > +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".


>
> > @@ -4654,7 +4654,8 @@ DEFUN ("write-region", Fwrite_region,
> Swrite_region, 3, 7,
> >  When called from a program, requires three arguments:
> >  START, END and FILENAME.  START and END are normally buffer positions
> >  specifying the part of the buffer to write.
> > -If START is nil, that means to use the entire buffer contents.
> > +If START is nil, that means to use the entire buffer contents; END is
> > +ignored.
>
> Once again, please mention the accessible portion of the buffer.
>
>
See above, this function ignores narrowing.