Eli Zaretskii <
address@hidden> schrieb am Sa., 20. Aug. 2016 um 09:08 Uhr:
> From: Philipp Stephani <address@hidden>
> 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.