Re: Small docstring improvements

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> 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.