From 9b99772cf4b24443e1c096bb1e847da4cf502543 Mon Sep 17 00:00:00 2001
From: Philipp Stephani <phst@google.com>
Date: Fri, 19 Aug 2016 21:23:24 +0200
Subject: [PATCH] Some assorted documentation clarifications

* src/fileio.c (Fwrite_region): Clarify that END is ignored if
START is nil.
* src/editfns.c (Fbuffer_size): Add short discussion about
narrowing.
* src/callproc.c (Fcall_process_region): Discuss behavior when
START and END are not buffer positions.
---
 src/callproc.c | 7 +++++++
 src/editfns.c  | 9 ++++++++-
 src/fileio.c   | 3 ++-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/callproc.c b/src/callproc.c
index 2fb5b1d5194..76b5caa4465 100644
--- a/src/callproc.c
+++ b/src/callproc.c
@@ -1005,6 +1005,13 @@ create_temp_file (ptrdiff_t nargs, Lisp_Object *args,
 DEFUN ("call-process-region", Fcall_process_region, Scall_process_region,
        3, MANY, 0,
        doc: /* Send text from START to END to a synchronous process running PROGRAM.
+
+START and END are normally buffer positions specifying the part of the
+buffer to send to the process.
+If START is nil, that means to use the entire buffer contents; END is
+ignored.
+If START is a string, then send that string to the process
+instead of any buffer contents; END is ignored.
 The remaining arguments are optional.
 Delete the text if fourth arg DELETE is non-nil.
 
diff --git a/src/editfns.c b/src/editfns.c
index 32c8bec6db2..e1c85166545 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1029,7 +1029,14 @@ 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 current buffer, use
+`(- (point-max) (point-min))', and to count the number of characters
+in some other BUFFER, use
+`(with-current-buffer BUFFER (- (point-max) (point-min)))'.  */)
   (Lisp_Object buffer)
 {
   if (NILP (buffer))
diff --git a/src/fileio.c b/src/fileio.c
index 3005ca320e7..c3b2be7c5f7 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -4644,7 +4644,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.
 If START is a string, then output that string to the file
 instead of any buffer contents; END is ignored.
 
-- 
2.11.4.GIT