Re: [lwip-devel] misleading @note in sys_untimeout

[Pomeroy, Marty]

> in the documentation of sys_untimeout, there is a warning note:

>> /**
>>  * Go through timeout list (for this task only) and remove the first 
>> matching
>>  * entry, even though the timeout has not triggered yet.
>>  *
>>  * @note This function only works as expected if there is only one 
>> timeout
>>  * calling 'handler' in the list of timeouts.
>>  *

> can you explain to me how the @note is relevant?


Hi Chrysn.

I would suspect that someone called sys_untimeout and spent hours trying
to debug why their handler was still being called, and it was due to a
second entry.  They added the note to emphasize the point.

You're right that the note is phrased incorrectly, since it does indeed
"work as expected" according to the description.

JMO and FWIW I personally don't find the extra emphasis objectionable,
but it could be improved perhaps as "@note  This function only removes
the first entry calling 'handler'.  Subsequent entries remain on the
list."  I wouldn't remove it completely - might save someone else some
time debugging their incorrect expectations.

Marty