add API documentation

diff --git a/src/lib/bio/packet.h b/src/lib/bio/packet.h
index ec0b537f87a2cf1a6957ffed2178349679d06250..c1151a99c4a5add84f51356bc48b997203717ba2 100644 (file)
--- a/src/lib/bio/packet.h
+++ b/src/lib/bio/packet.h
@@ -76,11 +76,40 @@ struct fr_bio_packet_s {
 };
 
 
+/** Read a packet from a packet BIO
+ *
+ *  Note that the bio MAY return fr_bio_error(IO_WOULD_BLOCK), which is not a fatal error.  The caller has to
+ *  check for that case, and handle blocking errors.  Typically by pushing the packet to a queue, and trying
+ *  it again later.
+ *
+ * @param bio          the packet-based bio
+ * @param[out] request_ctx_p   the larger context for the original request packet
+ * @param[out] packet_p        Where the allocated #fr_packet_t will be stored
+ * @param[out_ctx]     for the output pairs
+ * @param[out]         decoded output pairs
+ * @return
+ *     - <0 on error.  This is fr_bio_error(FOO)
+ *     - 0 for success
+ */
 static inline CC_HINT(nonnull) int fr_bio_packet_read(fr_bio_packet_t *bio, void **request_ctx_p, fr_packet_t **packet_p, TALLOC_CTX *out_ctx, fr_pair_list_t *out)
 {
        return bio->read(bio, request_ctx_p, packet_p, out_ctx, out);
 }
 
+/** Write a packet to a packet BIO
+ *
+ *  Note that the bio MAY return fr_bio_error(IO_WOULD_BLOCK), which is not a fatal error.  The caller has to
+ *  check for that case, and handle blocking errors.  Typically by pushing the packet to a queue, and trying
+ *  it again later.
+ *
+ * @param bio          the packet-based bio
+ * @param request_ctx  the larger context for the packet
+ * @param packet       the output packet descriptor.  Contains raw protocol data (IDs, counts, etc.)
+ * @param list         of pairs to write
+ * @return
+ *     - <0 on error.  This is fr_bio_error(FOO)
+ *     - 0 for success
+ */
 static inline CC_HINT(nonnull) int fr_bio_packet_write(fr_bio_packet_t *bio, void *request_ctx, fr_packet_t *packet, fr_pair_list_t *list)
 {
        return bio->write(bio, request_ctx, packet, list);