Jerome BENOIT <sphericaltrian...@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