Re: lintian: spelling

[Ben Finney <bignose@debian.org>]

Jerome BENOIT <sphericaltriangle@rezozer.net> writes:

> Hi,
>
> On 21/10/16 12:56, Ben Finney wrote:
> > I would suggest:
> > 
> >     :param int max_no_dec: number of rounds we allow [FIXME] to be stuck.
> > 
> > where “[FIXME]” must be replaced with something explicit. Is it “the
> > program”? “the network connection”? Some other party? It's not
> > specified, and I think Lintian is correct to complain.
>
> [FIXME] is certainly an obscure loop that is meant to stop any
> convergence that goes out of control.

Could that be broadened simply to “the function”?

> I guess that we can over come it through a passive sentence:

For documentation, passive sentences are almost certainly worse (less
clear, more ambiguous) than explicitly naming the active parties.

> 	:param int max_no_dec: number of rounds allowed to be stuck.

How about:

    :param int max_no_dec: number of rounds the function is allowed to be stuck.

Thank you for working to improve the software.

-- 
 \       “Anyone who puts a small gloss on [a] fundamental technology, |
  `\          calls it proprietary, and then tries to keep others from |
_o__)           building on it, is a thief.” —Tim O'Reilly, 2000-01-25 |
Ben Finney