| Message ID | 1433526691-20058-2-git-send-email-zoltan.kiss@linaro.org |
|---|---|
| State | New |
| Headers | show |
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
On 22 June 2015 at 13:00, Zoltan Kiss <zoltan.kiss@linaro.org> 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 > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h index 89356a6..5a71e52 100644 --- a/include/odp/api/packet_io.h +++ b/include/odp/api/packet_io.h @@ -111,7 +111,9 @@ int odp_pktio_recv(odp_pktio_t pktio, odp_packet_t pkt_table[], int len); * @param pkt_table[] Array of packets to send * @param len length of pkt_table[] * - * @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 */ int odp_pktio_send(odp_pktio_t pktio, odp_packet_t pkt_table[], int len); diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h index 6a8b15f..ac4147d 100644 --- a/include/odp/api/queue.h +++ b/include/odp/api/queue.h @@ -242,7 +242,8 @@ void *odp_queue_get_context(odp_queue_t queue); * @param ev Event handle * * @retval 0 on success - * @retval <0 on failure (e.g. queue full) + * @retval <0 on failure (e.g. queue full), the event is not consumed, caller + * has to take care of it. */ int odp_queue_enq(odp_queue_t queue, odp_event_t ev); @@ -253,7 +254,9 @@ int odp_queue_enq(odp_queue_t queue, odp_event_t ev); * @param[in] events Array of event handles * @param num Number of event handles to enqueue * - * @return Number of events actually enqueued (0 ... num) + * @return Number of events actually enqueued (0 ... num). If it is less than + * 'num', the remaining events at the end of events[] are not consumed, and + * caller has to take care of them. * @retval <0 on failure */ int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], int num);
Currently our examples are not handling this situation as well. Signed-off-by: Zoltan Kiss <zoltan.kiss@linaro.org> --- include/odp/api/packet_io.h | 4 +++- include/odp/api/queue.h | 7 +++++-- 2 files changed, 8 insertions(+), 3 deletions(-)