[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Small docstring improvements
From: |
Eli Zaretskii |
Subject: |
Re: Small docstring improvements |
Date: |
Sat, 20 Aug 2016 10:08:08 +0300 |
> 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.
> +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) */)
>
> 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.
Re: Small docstring improvements, Dmitry Gutov, 2016/08/19
Re: Small docstring improvements,
Eli Zaretskii <=