Merge branch 'lukeshu/docs'

1 files changed, 31 insertions, 10 deletions

diff --git a/lib9p/include/lib9p/9p.h b/lib9p/include/lib9p/9p.h
index f743afb..7724fc8 100644
--- a/lib9p/include/lib9p/9p.h
+++ b/lib9p/include/lib9p/9p.h
@@ -63,7 +63,7 @@ int lib9p_errorf(struct lib9p_ctx *ctx, uint32_t linux_errno, char const *fmt, .
 /* main T-message functions ***************************************************/
 
 /**
- * Validate a message's structure; it's size, string encodings, enums,
+ * Validate a message's structure; its size, string encodings, enums,
  * and bitfields.
  *
  * Return how much space the message will take when unmarshaled.  This
@@ -91,13 +91,10 @@ ssize_t lib9p_Tmsg_validate(struct lib9p_ctx *ctx, uint8_t *net_bytes);
 /**
  * Unmarshal the 9P message `net_bytes` into the C struct `ret_body`.
  *
- * Emits an error (return 0, set ctx->err_num and ctx->err_msg) if a
- * string contains invalid UTF-8 or a nul-byte.
- *
- * lib9p_unmarshal does no validation; you must run
+ * lib9p_Tmsg_unmarshal does no validation; you must run
  * lib9p_Tmsg_validate() first.
  *
- * @param ctx : negotiated protocol parameters, where to record errors
+ * @param ctx : negotiated protocol parameters
  * @param net_bytes : the complete message, starting with the "size[4]"
  *
  * @return ret_typ : the mesage type
@@ -152,17 +149,27 @@ static inline void lib9p_stat_assert(struct lib9p_stat stat) {
 }
 
 /**
- * TODO
+ * Validate a message's `stat` structure.
+ *
+ * @param ctx : negotiated protocol parameters, where to record errors
+ * @param net_bytes : network-encoded stat structure
+ * @param net_size : the number of net_bytes that may be read
  *
- * @return ret_net_size: number of bytes consumed; <=net_size
- * @return ret_host_size: number of bytes that lib9p_stat_unmarshal would take
+ * @return ret_net_size : number of bytes consumed; <=net_size
+ * @return ret_host_size : number of bytes that lib9p_stat_unmarshal would take
  * @return whether there was an error
  */
 bool lib9p_stat_validate(struct lib9p_ctx *ctx, uint32_t net_size, uint8_t *net_bytes,
                             uint32_t *ret_net_size, ssize_t *ret_host_size);
 
 /**
- * TODO
+ * Unmarshal the 9P `net_bytes` into the C struct `ret_obj`.
+ *
+ * lib9p_stat_unmarshal does no validation; you must run
+ * lib9p_stat_validate() first.
+ *
+ * @param ctx : negotiated protocol parameters
+ * @param net_bytes : network-encoded stat structure
  *
  * @return ret_obj : where to put the stat object itself
  * @return ret_extra : where to put strings for the stat object
@@ -172,8 +179,22 @@ uint32_t lib9p_stat_unmarshal(struct lib9p_ctx *ctx, uint8_t *net_bytes,
                               struct lib9p_stat *ret_obj, void *ret_extra);
 
 /**
+ * Marhsal a `struct lib9p_stat` structure into a byte-array.
+ *
+ * lib9p_Tmsg_marshal does no validation; it trusts that the
+ * programmer won't give it garbage input.  However, just as it
+ * doesn't marshal struct fields that aren't in ctx->version, it won't
+ * marshal bitfield bits that aren't in ctx->version; it applies a
+ * version-specific mask to bitfields.
+ *
+ * @param ctx : negotiated protocol parameters, where to record errors
+ * @param max_net_size : the maximum network-encoded size to allow
+ * @param obj : the message to encode
+ *
  * @return ret_bytes: the buffer to encode into
  * @return the number of bytes written, or 0 if the stat object does not fit in max_net_size
+ *
+ * @errno LINUX_ERANGE: reply does not fit in max_net_size
  */
 uint32_t lib9p_stat_marshal(struct lib9p_ctx *ctx, uint32_t max_net_size, struct lib9p_stat *obj,
                             uint8_t *ret_bytes);