Complete documentation for functions in libradsec-base.h.

1 files changed, 21 insertions, 13 deletions

diff --git a/lib/libradsec-base.h b/lib/libradsec-base.h
index 5a80ab8..57a86ef 100644
--- a/lib/libradsec-base.h
+++ b/lib/libradsec-base.h
@@ -61,32 +61,40 @@ int rs_connect(enum rs_conn_type type,
     errno is set appropriately.  */
 int rs_disconnect(int fd);
 
-/** Allocate and initialize a packet object from a buffer containing a
-    packet as seen on the wire.  Free the packet using @a
-    rs_packet_free().
+/** Allocate and initialize a packet from a buffer containing a packet
+    as seen on the wire.  Free the packet using @a rs_packet_free().
 
-    @param buf
-    @param buflen
-    @param count
+    @param buf Buffer with on-the-wire data with packet.
+    @param buflen Number of octets in @a buf.
+
+    @param count Number of octets used in buffer, in case of
+    successful construction of a packet (return !NULL) or number of
+    octets needed for a complete packet (return NULL).
 
     @return Packet or NULL on error or not enough data in @a buf.  If
     return value is NULL and @a count is < 0, an error has occurred
     and errno is set appropriately.  If return value is NULL and @a
     count is > 0 it shows the number of bytes needed to complete the
-    packet.
-*/
+    packet.  */
 struct rs_packet *rs_packet_new(const uint8_t *buf,
 				size_t buflen,
 				ssize_t *count);
 
-/** Free a packet object that has been allocated by @a
-    rs_packet_new().
-
+/** Free a packet that has been allocated by @a rs_packet_new().
 
-*/
+    @param packet Packet to free.  */
 void rs_packet_free(struct rs_packet *packet);
 
-/** Serialize a packet.  */
+/** Serialize a packet.
+
+    @param packet Packet to serialize.
+    @param buf Buffer to store the serialized packet in.
+    @param buflen Length of buffer.
+
+    @return Number of bytes written to buf or 0 if the buffer wasn't
+    large enough to hold the packet or < 0 in case the packet couldn't
+    be serialized for some other eason (FIXME: elaborate) */
+
 ssize_t rs_packet_serialize(const struct rs_packet *packet,
 			    uint8_t *buf,
 			    size_t buflen);