Re: Small docstring improvements

[Eli Zaretskii <eliz@gnu.org>]

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

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

> --- a/src/editfns.c
> +++ b/src/editfns.c
> @@ -1065,7 +1065,12 @@ usage: (save-current-buffer &rest BODY)  */)
>  \f
>  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.

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

Thanks.