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

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

[Hong Xu]

	* 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

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

[Tino Calancha]

Hong Xu <hong@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).

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

[npostavs]

Tino Calancha <tino.calancha@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.

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

[Tino Calancha]

On Sun, 2 Apr 2017, npostavs@users.sourceforge.net wrote:

> Tino Calancha <tino.calancha@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.

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

[eliz]

[-- Attachment #1: Type: text/plain, Size: 803 bytes --]


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

>> Tino Calancha <tino.calancha@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.



[-- Attachment #2: Type: text/html, Size: 1383 bytes --]

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

[npostavs]

tags 25193 fixed
close 25193 25.2
quit

eliz <eliz@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.

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

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

Hong Xu <hong@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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 472 bytes --]