On 09/06/15 13:45, Savolainen, Petri (Nokia - FI/Espoo) wrote:
- * @return Number of packets sent
>+ * @return Number of packets sent. If it is less than 'len', the
>remaining
>+ * packets at the end of pkt_table[] are not consumed, and caller has to
>take
>+ * care of them.
> * @retval <0 on failure
> */
I think that documentation in @param/@return/@retval should be compact. The
actual documentation body text is better place to describe what the function
does, what are the pre- and post-conditions, user responsibilities, etc
Generally I agree with compactness here, but my idea was that when the
lazy developer glances to the documentation during implementation to
check what are the return values, (s)he might not read the body text
again, so @return or @retval is a better place to raise attention to
this possible issue. Thoughts?
Zoli
_______________________________________________
lng-odp mailing list
[email protected]
https://lists.linaro.org/mailman/listinfo/lng-odp
