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

Previous Next

Full log

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.

Previous Next

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