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

Previous Next

Full log

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).

Previous Next

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