[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#29328: 24.5; doc string of `transpose-subr`
From: |
Drew Adams |
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.