GNU bug report logs - #25193
[PATCH] Improve the doc of re-search-forward and re-search-backward.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 25193 in the body.
You can then email your comments to 25193 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Improve the doc of re-search-forward and re-search-backward.
Date: Mon, 12 Dec 2016 19:20:31 -0800

	* search.c (Fre_search_forward, Fre_search_backward): Improve doc.
---
 src/search.c | 58 ++++++++++++++++++++++++----------------------------------
 1 file changed, 24 insertions(+), 34 deletions(-)

diff --git a/src/search.c b/src/search.c
index 9f55d728362a..81edc27ecdc8 100644
--- a/src/search.c
+++ b/src/search.c
@@ -2257,26 +2257,12 @@ See also the functions `match-beginning', `match-end' and `replace-match'.  */)
 
 DEFUN ("re-search-backward", Fre_search_backward, Sre_search_backward, 1, 4,
        "sRE search backward: ",
-       doc: /* Search backward from point for match for regular expression REGEXP.
-Set point to the beginning of the occurrence found, and return point.
-An optional second argument bounds the search; it is a buffer position.
-  The match found must not begin before that position.  A value of nil
-  means search to the beginning of the accessible portion of the buffer.
-Optional third argument, if t, means if fail just return nil (no error).
-  If not nil and not t, position at limit of search and return nil.
-Optional fourth argument COUNT, if a positive number, means to search
-  for COUNT successive occurrences.  If COUNT is negative, search
-  forward, instead of backward, for -COUNT occurrences.  A value of
-  nil means the same as 1.
-With COUNT positive, the match found is the COUNTth to last one (or
-  last, if COUNT is 1 or nil) in the buffer located entirely before
-  the origin of the search; correspondingly with COUNT negative.
-
-Search case-sensitivity is determined by the value of the variable
-`case-fold-search', which see.
+       doc: /* Search backward from point for regular expression REGEXP.
+This function is almost identical to `re-search-forward', except for
+that by default it searches backward instead of forward, and the sign
+of COUNT also indicates exactly the opposite searching direction.
 
-See also the functions `match-beginning', `match-end', `match-string',
-and `replace-match'.  */)
+See `re-search-forward' for details.  */)
   (Lisp_Object regexp, Lisp_Object bound, Lisp_Object noerror, Lisp_Object count)
 {
   return search_command (regexp, bound, noerror, count, -1, 1, 0);
@@ -2286,21 +2272,25 @@ DEFUN ("re-search-forward", Fre_search_forward, Sre_search_forward, 1, 4,
        "sRE search: ",
        doc: /* Search forward from point for regular expression REGEXP.
 Set point to the end of the occurrence found, and return point.
-An optional second argument bounds the search; it is a buffer position.
-  The match found must not end after that position.  A value of nil
-  means search to the end of the accessible portion of the buffer.
-Optional third argument, if t, means if fail just return nil (no error).
-  If not nil and not t, move to limit of search and return nil.
-Optional fourth argument COUNT, if a positive number, means to search
-  for COUNT successive occurrences.  If COUNT is negative, search
-  backward, instead of forward, for -COUNT occurrences.  A value of
-  nil means the same as 1.
-With COUNT positive, the match found is the COUNTth one (or first,
-  if COUNT is 1 or nil) in the buffer located entirely after the
-  origin of the search; correspondingly with COUNT negative.
-
-Search case-sensitivity is determined by the value of the variable
-`case-fold-search', which see.
+The optional second argument BOUND is a buffer position that bounds
+  the search.  The match found must not end after that position.  A
+  value of nil means search to the end of the accessible portion of
+  the buffer.
+The optional third argument NOERROR indicates how errors are handled
+  when the search fails.  If it is nil or omitted, emit an error; if
+  it is t, simply return nil and do nothing; if it is neither nil nor
+  t, move to the limit of search and return nil.
+The optional fourth argument COUNT is a number that indicates the
+  search direction and the number of occurrences to search for.  If it
+  is positive, search forward for COUNT successive occurrences; if it
+  is negative, search backward, instead of forward, for -COUNT
+  occurrences.  A value of nil means the same as 1.
+With COUNT positive/negative, the match found is the COUNTth/-COUNTth
+  one in the buffer located entirely after/before the origin of the
+  search.
+
+Search case-sensitivity is determined by the variable
+`case-fold-search'.
 
 See also the functions `match-beginning', `match-end', `match-string',
 and `replace-match'.  */)
-- 
2.1.4

Message #8 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: Tino Calancha <tino.calancha <at> gmail.com>
To: Hong Xu <hong <at> topbug.net>
Cc: tino.calancha <at> gmail.com, 25193 <at> debbugs.gnu.org
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward and
 re-search-backward.
Date: Tue, 13 Dec 2016 15:27:03 +0900

Hong Xu <hong <at> topbug.net> writes:

> 	* search.c (Fre_search_forward, Fre_search_backward): Improve doc.
> ---
>  src/search.c | 58 ++++++++++++++++++++++++----------------------------------
>  1 file changed, 24 insertions(+), 34 deletions(-)
>
> diff --git a/src/search.c b/src/search.c
> index 9f55d728362a..81edc27ecdc8 100644
> --- a/src/search.c
> +++ b/src/search.c
> @@ -2257,26 +2257,12 @@ See also the functions `match-beginning', `match-end' and `replace-match'.  */)
>  
>  DEFUN ("re-search-backward", Fre_search_backward, Sre_search_backward, 1, 4,
>         "sRE search backward: ",
> -       doc: /* Search backward from point for match for regular expression REGEXP.
> -Set point to the beginning of the occurrence found, and return point.
> -An optional second argument bounds the search; it is a buffer position.
> -  The match found must not begin before that position.  A value of nil
> -  means search to the beginning of the accessible portion of the buffer.
> -Optional third argument, if t, means if fail just return nil (no error).
> -  If not nil and not t, position at limit of search and return nil.
> -Optional fourth argument COUNT, if a positive number, means to search
> -  for COUNT successive occurrences.  If COUNT is negative, search
> -  forward, instead of backward, for -COUNT occurrences.  A value of
> -  nil means the same as 1.
> -With COUNT positive, the match found is the COUNTth to last one (or
> -  last, if COUNT is 1 or nil) in the buffer located entirely before
> -  the origin of the search; correspondingly with COUNT negative.
> -
> -Search case-sensitivity is determined by the value of the variable
> -`case-fold-search', which see.
> +       doc: /* Search backward from point for regular expression REGEXP.
> +This function is almost identical to `re-search-forward', except for
> +that by default it searches backward instead of forward, and the sign
> +of COUNT also indicates exactly the opposite searching direction.
>  
> -See also the functions `match-beginning', `match-end', `match-string',
> -and `replace-match'.  */)
> +See `re-search-forward' for details.  */)
Thanks for the report.
You could refer for details to the manual, maybe providing a link to the
proper node; but you don't want to refer to the doc string of another
function 'B' to document the arguments of the current function 'A'.
IMO the doc string of 'A' must introduce all its arguments.

Otherwise, i am worry you could go an step further, f.i.
`search-forward'/ `search-backward' share the same optional arguments, so:

1) doc string `re-search-backward': See the doc string of `re-search-forward'
   for details.
2)  doc string `re-search-forward': See the doc string of
   `search-backward' for details.
3)  doc string `search-backward': See the doc string of
   `search-forward' for details.
4)  doc string `search-forward': Wow, you are are very persistent
    user! Please see the manual for details, i am a very busy doc string.

(Reminds me the paperwork in some public agencies).

Message #11 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Tino Calancha <tino.calancha <at> gmail.com>
Cc: 25193 <at> debbugs.gnu.org, Hong Xu <hong <at> topbug.net>
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward and
 re-search-backward.
Date: Sun, 02 Apr 2017 00:42:57 -0400

Tino Calancha <tino.calancha <at> gmail.com> writes:

> Thanks for the report.
> You could refer for details to the manual, maybe providing a link to the
> proper node; but you don't want to refer to the doc string of another
> function 'B' to document the arguments of the current function 'A'.
> IMO the doc string of 'A' must introduce all its arguments.
>
> Otherwise, i am worry you could go an step further, f.i.
> `search-forward'/ `search-backward' share the same optional arguments, so:

I think it's okay to point to other functions, as long as we keep the
chain to length 1.

> 1) doc string `re-search-backward': See the doc string of `re-search-forward'
>    for details.
> 2)  doc string `re-search-forward': See the doc string of
>    `search-backward' for details.
> 3)  doc string `search-backward': See the doc string of
>    `search-forward' for details.
> 4)  doc string `search-forward': Wow, you are are very persistent
>     user! Please see the manual for details, i am a very busy doc string.

:D

But if all of `re-search-backword', re-search-forward',
`search-backward', would say "see doc string of `search-forward'" I
think it would be okay.

Message #14 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: Tino Calancha <tino.calancha <at> gmail.com>
To: npostavs <at> users.sourceforge.net
Cc: Hong Xu <hong <at> topbug.net>, 25193 <at> debbugs.gnu.org,
 Tino Calancha <tino.calancha <at> gmail.com>
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward and
 re-search-backward.
Date: Sun, 2 Apr 2017 13:57:00 +0900 (JST)

On Sun, 2 Apr 2017, npostavs <at> users.sourceforge.net wrote:

> Tino Calancha <tino.calancha <at> gmail.com> writes:
>
>> Thanks for the report.
>> You could refer for details to the manual, maybe providing a link to the
>> proper node; but you don't want to refer to the doc string of another
>> function 'B' to document the arguments of the current function 'A'.
>> IMO the doc string of 'A' must introduce all its arguments.
>>
>> Otherwise, i am worry you could go an step further, f.i.
>> `search-forward'/ `search-backward' share the same optional arguments, so:
>
> I think it's okay to point to other functions, as long as we keep the
> chain to length 1.
Maybe OK (see below for the rest of my answer, like in my example :)
>> 1) doc string `re-search-backward': See the doc string of `re-search-forward'
>>    for details.
>> 2)  doc string `re-search-forward': See the doc string of
>>    `search-backward' for details.
>> 3)  doc string `search-backward': See the doc string of
>>    `search-forward' for details.
>> 4)  doc string `search-forward': Wow, you are are very persistent
>>     user! Please see the manual for details, i am a very busy doc string.
>
> :D
>
> But if all of `re-search-backword', re-search-forward',
> `search-backward', would say "see doc string of `search-forward'" I
> think it would be okay.
OK for me if it's just 1 jump, but i slightly prefer self-contained
docstrings.  Don't know what Eli or John might think about it.

Message #17 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: eliz <eliz <at> gnu.org>
To: Tino Calancha <tino.calancha <at> gmail.com>, npostavs <at> users.sourceforge.net
Cc: Hong Xu <hong <at> topbug.net>, 25193 <at> debbugs.gnu.org
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward and
 	re-search-backward.
Date: Sun, 02 Apr 2017 09:21:16 +0300

[Message part 1 (text/plain, inline)]

-------- הודעה מקורית --------מאת: Tino Calancha <tino.calancha <at> gmail.com> תאריך: 2.4.2017  07:57  (GMT+02:00) אל: npostavs <at> users.sourceforge.net עותק: 25193 <at> debbugs.gnu.org, Tino Calancha <tino.calancha <at> gmail.com>, Hong Xu <hong <at> topbug.net> נושא: bug#25193: [PATCH] Improve the doc of re-search-forward and
 	re-search-backward. 
On Sun, 2 Apr 2017, npostavs <at> users.sourceforge.net wrote:

>> Tino Calancha <tino.calancha <at> gmail.com> 
>> :D
>>
>> But if all of `re-search-backword', re-search-forward',
>> `search-backward', would say "see doc string of `search-forward'" I
>> think it would be okay.
>OK for me if it's just 1 jump, but i slightly prefer self-contained
>docstrings.  Don't know what Eli or John might >think about it.


One hop is fine with me, thanks.

[Message part 2 (text/html, inline)]

Message #22 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: eliz <eliz <at> gnu.org>
Cc: Hong Xu <hong <at> topbug.net>, 25193 <at> debbugs.gnu.org,
 Tino Calancha <tino.calancha <at> gmail.com>
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward and
 re-search-backward.
Date: Thu, 06 Apr 2017 19:19:32 -0400

tags 25193 fixed
close 25193 25.2
quit

eliz <eliz <at> gnu.org> writes:

>>>
>>> But if all of `re-search-backword', re-search-forward',
>>> `search-backward', would say "see doc string of `search-forward'" I
>>> think it would be okay.
>>OK for me if it's just 1 jump, but i slightly prefer self-contained
>>docstrings. Don't know what Eli or John might >think about it.
>
> One hop is fine with me, thanks.

Okay, pushed to emacs-25.

Message #29 received at 25193 <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Petton <nicolas <at> petton.fr>
To: Hong Xu <hong <at> topbug.net>, 25193 <at> debbugs.gnu.org
Subject: Re: bug#25193: [PATCH] Improve the doc of re-search-forward
 and	re-search-backward.
Date: Fri, 14 Apr 2017 17:12:56 +0200

[Message part 1 (text/plain, inline)]

Hong Xu <hong <at> topbug.net> writes:

Hi Hong,

Thanks for the patch.

> 	* search.c (Fre_search_forward, Fre_search_backward): Improve
> 	doc.

Could you in the future add the path of files in commit messages?
Your commit message would have looked like this:

  * src/search.c (Fre_search_forward, Fre_search_backward): Improve doc.

We use commit messages to generate changelog files, and keep the
etc/AUTHORS file up-to-date.

Cheers,
Nico

[signature.asc (application/pgp-signature, inline)]

Previous Next

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