-@defun barf-if-buffer-read-only
-This function signals a @code{buffer-read-only} error if the current
-buffer is read-only. @xref{Interactive Call}, for another way to
-signal an error if the current buffer is read-only.
+@defun barf-if-buffer-read-only &optional buffer start end
+This function signals a @code{buffer-read-only} error if @var{buffer} is
+read-only. @var{buffer} defaults to the current buffer.
+@xref{Interactive Call}, for another way to signal an error if the
+current buffer is read-only.
+
+If optional argument @var{start} is non-@code{nil}, all extents in the
+buffer which overlap that part of the buffer are checked to ensure none
+has a @code{read-only} property. (Extents that lie completely within the
+range, however, are not checked.) @var{end} defaults to the value of
+@var{start}.
+
+If @var{start} and @var{end} are equal, the range checked is
+[@var{start}, @var{end}] (i.e. closed on both ends); otherwise, the
+range checked is (@var{start}, @var{end}) \(open on both ends), except
+that extents that lie completely within [@var{start}, @var{end}] are not
+checked. See @code{extent-in-region-p} for a fuller discussion.