On 22 June 2015 at 13:00, Zoltan Kiss <[email protected]> wrote:
> > > 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? > I am catching up on mail, but if this is still relevant I agree. Lets spell out specifics in @retval where we can, specific cases makes them easy to identify and to add to the test suite. But generally if there is some important note lets use doxygen to highlight it with @note or @warning > > Zoli > > _______________________________________________ > lng-odp mailing list > [email protected] > https://lists.linaro.org/mailman/listinfo/lng-odp > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
_______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
