GNU bug report logs - #29328
24.5; doc string of `transpose-subr`

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 29328 <at> debbugs.gnu.org
Subject: bug#29328: 24.5; doc string of `transpose-subr`
Date: Fri, 17 Nov 2017 07:36:28 -0800 (PST)

> >> > The doc string should describe each parameter.  Parameter SPECIAL is
> >> > not described, and its name is not specific or enlightening.
> >>
> >> I don't see how it can be meaningfully documented.
> >
> > That's tantamount to saying that the parameter has no meaning,
> > no behavior.  If it does something then that something should
> > be describable, in some way, at least.  The place to start is
> > with the intention - why do we have such a parameter?  What
> > does it let you do?  Why/when would code ever make use of it?
> 
> How about something like this:
> -forward-paragraph).  If ARG is zero, exchanges the current object
> +forward-paragraph).  If SPECIAL is non-nil, then MOVER should
> +return the bounds of the object as a cons (BEG . END) instead.
> +If ARG is zero, exchanges the current object
>  with the one containing mark.  If ARG is an integer, moves the
>  current object past ARG following (if ARG is positive) or
>  preceding (if ARG is negative) objects, leaving point after the

If that's the behavior, fine with me.  I don't know
what the behavior is.

But the parameters should be described in order,
i.e., ARGS should be described before SPECIAL.

Previous Next

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