From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Tino Calancha Newsgroups: gmane.emacs.bugs Subject: bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward. Date: Tue, 13 Dec 2016 15:27:03 +0900 Message-ID: <87mvg0pcnc.fsf@gmail.com> References: <1481599231-19381-1-git-send-email-hong@topbug.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1481610497 19779 195.159.176.226 (13 Dec 2016 06:28:17 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 13 Dec 2016 06:28:17 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) Cc: 25193@debbugs.gnu.org, tino.calancha@gmail.com To: Hong Xu Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Dec 13 07:28:12 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cGgZO-0003rE-8t for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Dec 2016 07:28:10 +0100 Original-Received: from localhost ([::1]:35602 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cGgZS-0001gF-1o for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Dec 2016 01:28:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58962) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cGgZL-0001fv-KN for bug-gnu-emacs@gnu.org; Tue, 13 Dec 2016 01:28:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cGgZG-0005PM-Ly for bug-gnu-emacs@gnu.org; Tue, 13 Dec 2016 01:28:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:52863) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cGgZG-0005PF-IT for bug-gnu-emacs@gnu.org; Tue, 13 Dec 2016 01:28:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cGgZG-0001Fh-0n for bug-gnu-emacs@gnu.org; Tue, 13 Dec 2016 01:28:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Tino Calancha Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 13 Dec 2016 06:28:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25193 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 25193-submit@debbugs.gnu.org id=B25193.14816104454767 (code B ref 25193); Tue, 13 Dec 2016 06:28:01 +0000 Original-Received: (at 25193) by debbugs.gnu.org; 13 Dec 2016 06:27:25 +0000 Original-Received: from localhost ([127.0.0.1]:40029 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cGgYd-0001En-GU for submit@debbugs.gnu.org; Tue, 13 Dec 2016 01:27:23 -0500 Original-Received: from mail-pf0-f196.google.com ([209.85.192.196]:36559) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cGgYc-0001Ea-Ce for 25193@debbugs.gnu.org; Tue, 13 Dec 2016 01:27:22 -0500 Original-Received: by mail-pf0-f196.google.com with SMTP id c4so5506709pfb.3 for <25193@debbugs.gnu.org>; Mon, 12 Dec 2016 22:27:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=BSDgvVgSQiYtLorCSE1YFVr36zrJUSNozh8G/vzeC14=; b=0f+sXm05J/oYmkOS6uMAjXrYaKM65zLLncJL5NIBvVUJrFly9FB9fjYZnj2pPl0RXd ecBAVusxXLuJM96znJPh67wF+KySbheZ1mnchtCoCgFDISvfkiO07pwvLSxjg5r6bzIt mW7Gtx1iZ+3FxMA+UhZd0Pr8pS4Pr7jwa783HOfebqo2JxE8mB5V3YW+r+vhH559HqIE 4qcp4jiQ2koWS6GCdIeEZXtiT4Tvoz9xeaShPf1m//XZm2zGnib4VR2iVbiGGnIF8jcv BXABFwHeGPHJtx/AWMrbKuhuXNWsyS/wfrZdGW5lMdJ4m4ZL64hrDeo46MttsSx+sXrr 59xQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=BSDgvVgSQiYtLorCSE1YFVr36zrJUSNozh8G/vzeC14=; b=LIEI+RdoroyTJ/8W/0jxjHc9chbXEXEC1Y2OUFZI0CBLXKC/s+DrkvWViU7Yos92du 8Bu8r/9yiUHp8LWXHElt16RK2WAuDaP1TeE9JEU9XhirJIjqe5pPwzgewPSA+7c0/JBR SVZHEkR2HMldVoWcvQqRJoHwvHG3PzPYuhRqE5np3n/HRDOqaUOBukn0+p0J122ZtJt8 V54fXYF0F1blvoDXtrM9+p/cyTZRxOyXfbCjCEv6KIvRl9XH5bcmOg+xldWelN+CRpD5 aSHZkrx5xGXq+DR/poBqQmfM8fvaQL1Y84QXqikAB5Gx/8d3R4ldK5A1/w2WvrlXmHr6 lQBA== X-Gm-Message-State: AKaTC01JuNcdHOJUq4/L5BD2l+Un+zycCBI5ho6sCifb8fcg57Klt6dq2V4w8M1CKvjcPg== X-Received: by 10.98.76.8 with SMTP id z8mr100177319pfa.167.1481610436466; Mon, 12 Dec 2016 22:27:16 -0800 (PST) Original-Received: from calancha-pc (177.192.218.133.dy.bbexcite.jp. [133.218.192.177]) by smtp.gmail.com with ESMTPSA id y15sm79383583pgc.43.2016.12.12.22.27.14 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 12 Dec 2016 22:27:15 -0800 (PST) In-Reply-To: <1481599231-19381-1-git-send-email-hong@topbug.net> (Hong Xu's message of "Mon, 12 Dec 2016 19:20:31 -0800") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:126973 Archived-At: Hong Xu 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).