GNU bug report logs - #6493
24.0.50; doc strings of region-beginning, region-end

Previous Next

Full log

View this message in rfc822 format

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Deniz Dogan <deniz.a.m.dogan <at> gmail.com>
Cc: 6493 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: bug#6493: 
Date: Fri, 23 Jul 2010 11:30:47 +0200

On Fri, Jul 23, 2010 at 11:10, Deniz Dogan <deniz.a.m.dogan <at> gmail.com> wrote:

> Attached is a new patch.

Thanks.

Three comments:

 - You changed "Return" to "Returns", but it is standard Emacs
practice to make the first line in a docstring imperative. From
(elisp) D.6 "Tips for Documentation Strings":

  For consistency, phrase the verb in the first sentence of a
  function's documentation string as an imperative--for instance,
  use "Return the cons of A and B." in preference to "Returns the
  cons of A and B."

- You didn't write ChangeLog entries. They are trivial in this case
(so no need to resend), but usually a patch should include them.

- This thead has been just Drew and you, and I'm not sure the result
is better. Though I understand Drew's arguments, it is still a bit
weird to me to look at the docstring of region-(beginning|end) and not
to see *any* reference to the region (yes, I know it is implicit in
"point or mark"). So I'd like to hear more opinions.

    Juanma


=== modified file 'src/editfns.c'
--- src/editfns.c	2010-06-16 20:08:41 +0000
+++ src/editfns.c	2010-06-27 12:22:00 +0000
@@ -349,14 +349,18 @@
 }

 DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
-       doc: /* Return position of beginning of region, as an integer.  */)
+       doc: /* Returns the smaller of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set.  */)
      ()
 {
   return region_limit (1);
 }

 DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
-       doc: /* Return position of end of region, as an integer.  */)
+       doc: /* Returns the larger of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set.  */)
      ()
 {
   return region_limit (0);

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.