> -----Original Message----- > From: ext Zoltan Kiss [mailto:[email protected]] > Sent: Monday, June 22, 2015 8:00 PM > To: Savolainen, Petri (Nokia - FI/Espoo); [email protected] > Subject: Re: [lng-odp] [API-NEXT PATCH v3 1/9] api: packet_io: clarify > what happens when not all packets are sent > > > > 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
Doxygen documentation is also the ODP API spec, it's not only for users but also for implementers. I think it's better to concentrate the spec into the body of the documentation and then possibly refer to that from @param, @return, @note, etc doxygen decoration. Something like this: /** * Send packets * * Sends packets out through the specified interface. When successful, returns number * of packets actually sent. If the return value is less than 'len', the remaining * packets at the end of pkt_table[] are not consumed, and caller has to take * care of them. * * @param pktio Packet IO interface * @param pkt_table[] Array of packets to send * @param len length of pkt_table[] * * @return Number of packets actually sent * @retval <0 on failure */ int odp_pktio_send(odp_pktio_t pktio, odp_packet_t pkt_table[], int len); -Petri _______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
