moar doc

include/psyc/packet.h

@@ -18,43 +18,58 @@
 #include <psyc.h>
 #include <psyc/syntax.h>
 
+/** Modifier flags. */
 typedef enum
 {
+	/// Modifier needs to be checked if it needs length.
 	PSYC_MODIFIER_CHECK_LENGTH = 0,
+	/// Modifier needs length.
 	PSYC_MODIFIER_NEED_LENGTH = 1,
+	/// Modifier doesn't need length.
 	PSYC_MODIFIER_NO_LENGTH = 2,
+	/// Routing modifier, which implies that it doesn't need length.
 	PSYC_MODIFIER_ROUTING = 3,
 } psycModifierFlag;
 
+/** List flags. */
 typedef enum
 {
+	/// List needs to be checked if it needs length.
 	PSYC_LIST_CHECK_LENGTH = 0,
+	/// List needs length.
 	PSYC_LIST_NEED_LENGTH = 1,
+	/// List doesn't need length.
 	PSYC_LIST_NO_LENGTH = 2,
 } psycListFlag;
 
+/** Packet flags. */
 typedef enum
 {
+	/// Packet needs to be checked if it needs content length.
 	PSYC_PACKET_CHECK_LENGTH = 0,
+	/// Packet needs content length.
 	PSYC_PACKET_NEED_LENGTH = 1,
+	/// Packet doesn't need content length.
 	PSYC_PACKET_NO_LENGTH = 2,
 } psycPacketFlag;
 
-/** intermediate struct for a PSYC variable modification */
+/** Structure for a modifier. */
 typedef struct
-{
+t{
 	char oper;
 	psycString name;
 	psycString value;
 	psycModifierFlag flag;
 } psycModifier;
 
+/** Structure for an entity or routing header. */
 typedef struct
 {
 	size_t lines;
 	psycModifier *modifiers;
 } psycHeader;
 
+/** Structure for a list. */
 typedef struct
 {
 	size_t num_elems;
@@ -68,16 +83,16 @@ typedef struct
 {
 	psycHeader routing;	///< Routing header.
 	psycHeader entity;	///< Entity header.
-	psycString method;
+	psycString method; ///< Contains the method.
-	psycString data;
+	psycString data; ///< Contains the data.
-	psycString content;
+	psycString content; ///< Contains the whole content.
 	size_t routingLength;	///< Length of routing part.
 	size_t contentLength;	///< Length of content part.
 	size_t length;		///< Total length of packet.
-	psycPacketFlag flag;
+	psycPacketFlag flag; ///< Packet flag.
 } psycPacket;
 
-/** Check if a modifier needs length */
+/** Check if a modifier needs length. */
 static inline
 psycModifierFlag psyc_checkModifierLength (psycModifier *m)
 {
@@ -93,7 +108,7 @@ psycModifierFlag psyc_checkModifierLength (psycModifier *m)
 	return flag;
 }
 
-/** Create new modifier */
+/** Create new modifier. */
 static inline
 psycModifier psyc_newModifier (char oper, psycString *name, psycString *value,
                                psycModifierFlag flag)
@@ -119,40 +134,42 @@ psycModifier psyc_newModifier2 (char oper,
 	return psyc_newModifier(oper, &n, &v, flag);
 }
 
-/** Get the total length of a modifier. */
+/** Get the total length of a modifier when rendered. */
 size_t psyc_getModifierLength (psycModifier *m);
 
-/** Check if a list needs length */
+/** Check if a list needs length. */
 psycListFlag psyc_checkListLength (psycList *list);
 
-/** Get the total length of a list. */
+/** Get the total length of a list when rendered. */
 psycListFlag psyc_getListLength (psycList *list);
 
-/** Check if a packet needs length */
+/** Check if a packet needs length. */
 psycPacketFlag psyc_checkPacketLength (psycPacket *p);
 
-/** Calculate and set the length of packet parts and total packet length  */
+/** Calculate and set the rendered length of packet parts and total packet length.  */
 size_t psyc_setPacketLength (psycPacket *p);
 
-/** Create new list */
+/** Create new list. */
 psycList psyc_newList (psycString *elems, size_t num_elems, psycListFlag flag);
 
-/** Create new packet */
+/** Create new packet. */
 psycPacket psyc_newPacket (psycHeader *routing,
                            psycHeader *entity,
                            psycString *method, psycString *data,
                            psycPacketFlag flag);
 
-/** Create new packet */
+/** Create new packet. */
 psycPacket psyc_newPacket2 (psycModifier *routing, size_t routinglen,
                             psycModifier *entity, size_t entitylen,
                             const char *method, size_t methodlen,
                             const char *data, size_t datalen,
                             psycPacketFlag flag);
 
+/** Create new packet with raw content. */
 psycPacket psyc_newRawPacket (psycHeader *routing, psycString *content,
                               psycPacketFlag flag);
 
+/** Create new packet with raw content. */
 psycPacket psyc_newRawPacket2 (psycModifier *routing, size_t routinglen,
                                const char *content, size_t contentlen,
                                psycPacketFlag flag);

include/psyc/parse.h

@@ -117,7 +117,8 @@ typedef enum
 {
 	/// Parse only the header
 	PSYC_PARSE_ROUTING_ONLY = 1,
-	/// Parse only the content. Parsing starts at the content and the content must be complete.
+	/// Parse only the content.
+	/// Parsing starts at the content and the content must be complete.
 	PSYC_PARSE_START_AT_CONTENT = 2,
 } psycParseFlag;
 
@@ -127,61 +128,61 @@ typedef enum
  */
 typedef enum
 {
-/// Error, packet is not ending with a valid delimiter.
+	/// Error, packet is not ending with a valid delimiter.
 	PSYC_PARSE_ERROR_END = -8,
-/// Error, expected NL after the method.
+	/// Error, expected NL after the method.
 	PSYC_PARSE_ERROR_METHOD = -7,
-/// Error, expected NL after a modifier.
+	/// Error, expected NL after a modifier.
 	PSYC_PARSE_ERROR_MOD_NL = -6,
-/// Error, modifier length is not numeric.
+	/// Error, modifier length is not numeric.
 	PSYC_PARSE_ERROR_MOD_LEN = -5,
-/// Error, expected TAB before modifier value.
+	/// Error, expected TAB before modifier value.
 	PSYC_PARSE_ERROR_MOD_TAB = -4,
-/// Error, modifier name is missing.
+	/// Error, modifier name is missing.
 	PSYC_PARSE_ERROR_MOD_NAME = -3,
-/// Error, expected NL after the content length.
+	/// Error, expected NL after the content length.
 	PSYC_PARSE_ERROR_LENGTH = -2,
-/// Error in packet.
+	/// Error in packet.
 	PSYC_PARSE_ERROR = -1,
-/// Buffer contains insufficient amount of data.
+	/// Buffer contains insufficient amount of data.
-/// Fill another buffer and concatenate it with the end of the current buffer,
+	/// Fill another buffer and concatenate it with the end of the current buffer,
-/// from the cursor position to the end.
+	/// from the cursor position to the end.
 	PSYC_PARSE_INSUFFICIENT = 1,
-/// Routing modifier parsing done.
+	/// Routing modifier parsing done.
-/// Operator, name & value contains the respective parts.
+	/// Operator, name & value contains the respective parts.
 	PSYC_PARSE_ROUTING = 2,
-/// Start of an incomplete entity modifier.
+	/// Start of an incomplete entity modifier.
-/// Operator & name are complete, value is incomplete.
+	/// Operator & name are complete, value is incomplete.
 	PSYC_PARSE_ENTITY_START = 3,
-/// Continuation of an incomplete entity modifier.
+	/// Continuation of an incomplete entity modifier.
 	PSYC_PARSE_ENTITY_CONT = 4,
-/// End of an incomplete entity modifier.
+	/// End of an incomplete entity modifier.
 	PSYC_PARSE_ENTITY_END = 5,
-/// Entity modifier parsing done in one go.
+	/// Entity modifier parsing done in one go.
-/// Operator, name & value contains the respective parts.
+	/// Operator, name & value contains the respective parts.
 	PSYC_PARSE_ENTITY = 6,
-/// Start of an incomplete body.
+	/// Start of an incomplete body.
-/// Name contains method, value contains part of the body.
+	/// Name contains method, value contains part of the body.
 	PSYC_PARSE_BODY_START = 7,
-/// Continuation of an incomplete body.
+	/// Continuation of an incomplete body.
 	PSYC_PARSE_BODY_CONT = 8,
-/// End of an incomplete body.
+	/// End of an incomplete body.
 	PSYC_PARSE_BODY_END = 9,
-/// Body parsing done in one go, name contains method, value contains body.
+	/// Body parsing done in one go, name contains method, value contains body.
 	PSYC_PARSE_BODY = 10,
-/// Start of an incomplete content, value contains part of content.
+	/// Start of an incomplete content, value contains part of content.
-/// Used when PSYC_PARSE_ROUTING_ONLY is set.
+	/// Used when PSYC_PARSE_ROUTING_ONLY is set.
 	PSYC_PARSE_CONTENT_START = 7,
-/// Continuation of an incomplete body.
+	/// Continuation of an incomplete body.
-/// Used when PSYC_PARSE_ROUTING_ONLY is set.
+	/// Used when PSYC_PARSE_ROUTING_ONLY is set.
 	PSYC_PARSE_CONTENT_CONT = 8,
-/// End of an incomplete body.
+	/// End of an incomplete body.
-/// Used when PSYC_PARSE_ROUTING_ONLY is set.
+	/// Used when PSYC_PARSE_ROUTING_ONLY is set.
 	PSYC_PARSE_CONTENT_END = 9,
-/// Content parsing done in one go, value contains the whole content.
+	/// Content parsing done in one go, value contains the whole content.
-/// Used when PSYC_PARSE_ROUTING_ONLY is set.
+	/// Used when PSYC_PARSE_ROUTING_ONLY is set.
 	PSYC_PARSE_CONTENT = 10,
-/// Finished parsing packet.
+	/// Finished parsing packet.
 	PSYC_PARSE_COMPLETE = 11,
 } psycParseRC;
 
@@ -196,11 +197,11 @@ typedef enum
 	PSYC_PARSE_LIST_ERROR_TYPE = -3,
 	PSYC_PARSE_LIST_ERROR_NAME = -2,
 	PSYC_PARSE_LIST_ERROR = -1,
-/// Completed parsing a list element.
+	/// Completed parsing a list element.
 	PSYC_PARSE_LIST_ELEM = 1,
-/// Reached end of buffer.
+	/// Reached end of buffer.
 	PSYC_PARSE_LIST_END = 2,
-/// Binary list is incomplete.
+	/// Binary list is incomplete.
 	PSYC_PARSE_LIST_INCOMPLETE = 3,
 } psycParseListRC;
 
@@ -209,19 +210,19 @@ typedef enum
  */
 typedef struct
 {
-	size_t cursor; ///< current position in buffer
+	size_t cursor; ///< Current position in buffer.
-	size_t startc; ///< position where the parsing would be resumed
+	size_t startc; ///< Position where the parsing would be resumed.
-	psycString buffer; ///< buffer with data to be parsed
+	psycString buffer; ///< Buffer with data to be parsed.
-	uint8_t flags; ///< flags for the parser, see psycParseFlag
+	uint8_t flags; ///< Flags for the parser, see psycParseFlag.
-	psycPart part; ///< part of the packet being parsed currently
+	psycPart part; ///< Part of the packet being parsed currently.
 
-	size_t routingLength; ///< length of routing part parsed so far
+	size_t routingLength; ///< Length of routing part parsed so far.
-	size_t contentParsed; ///< number of bytes parsed from the content so far
+	size_t contentParsed; ///< Number of bytes parsed from the content so far.
-	size_t contentLength; ///< expected length of the content
+	size_t contentLength; ///< Expected length of the content.
-	psycBool contentLengthFound; ///< is there a length given for this packet?
+	psycBool contentLengthFound; ///< Is there a length given for this packet?
-	size_t valueParsed; ///< number of bytes parsed from the value so far
+	size_t valueParsed; ///< Number of bytes parsed from the value so far.
-	size_t valueLength; ///< expected length of the value
+	size_t valueLength; ///< Expected length of the value.
-	psycBool valueLengthFound; ///< is there a length given for this modifier?
+	psycBool valueLengthFound; ///< Is there a length given for this modifier?
 } psycParseState;
 
 /**
@@ -229,13 +230,13 @@ typedef struct
  */
 typedef struct
 {
-	size_t cursor; ///< current position in buffer
+	size_t cursor; ///< Current position in buffer.
-	size_t startc; ///< line start position
+	size_t startc; ///< Line start position.
-	psycString buffer;
+	psycString buffer; ///< Buffer with data to be parsed.
-	psycListType type; ///< list type
+	psycListType type; ///< List type.
 
-	size_t elemParsed; ///< number of bytes parsed from the elem so far
+	size_t elemParsed; ///< Number of bytes parsed from the elem so far.
-	size_t elemLength; ///< expected length of the elem
+	size_t elemLength; ///< Expected length of the elem.
 } psycParseListState;
 
 /**

include/psyc/render.h

@@ -21,21 +21,49 @@
  */
 typedef enum
 {
-	PSYC_RENDER_ERROR_METHOD_MISSING = -3, ///< method missing, but data present
+	/// Error, method is missing, but data is present.
-	PSYC_RENDER_ERROR_MODIFIER_NAME_MISSING = -2, ///< modifier name missing
+	PSYC_RENDER_ERROR_METHOD_MISSING = -3,
+	/// Error, a modifier name is missing.
+	PSYC_RENDER_ERROR_MODIFIER_NAME_MISSING = -2,
+	/// Error, buffer is too small to render the packet.
 	PSYC_RENDER_ERROR = -1,
+	/// Packet is rendered successfully in the buffer.
 	PSYC_RENDER_SUCCESS = 0,
 } psycRenderRC;
 
+/**
+ * Return codes for psyc_renderList.
+ */
+typedef enum
+{
+	/// Error, buffer is too small to render the list.
+	PSYC_RENDER_LIST_ERROR = -1,
+	/// List is rendered successfully in the buffer.
+	PSYC_RENDER_LIST_SUCCESS = 0,
+} psycRenderListRC;
+
 /**
  * Render a PSYC packet into a buffer.
+ *
+ * The packet structure should contain the packet parts, either routing, entity,
+ * method & data, or routing & content when rendering raw content.
+ * It should also contain the contentLength & total length of the packet,
+ * you can use psyc_setPacketLength for calculating & setting these values.
+ * This function renders packet->length bytes to buffer,
+ * if it doesn't fit in the buffer an error is returned.
+ *
+ * @see psyc_newPacket
+ * @see psyc_newPacket2
+ * @see psyc_newRawPacket
+ * @see psyc_newRawPacket2
+ * @see psyc_setPacketLength
  */
 psycRenderRC psyc_render (psycPacket *packet, char *buffer, size_t buflen);
 
 /**
  * Render a PSYC list into a buffer.
  */
-psycRenderRC psyc_renderList (psycList *list, char *buffer, size_t buflen);
+psycRenderListRC psyc_renderList (psycList *list, char *buffer, size_t buflen);
 
 /** @} */ // end of render group
 

src/render.c

@@ -2,13 +2,13 @@
 #include <psyc/render.h>
 #include <psyc/syntax.h>
 
-psycRenderRC psyc_renderList (psycList *list, char *buffer, size_t buflen)
+psycRenderListRC psyc_renderList (psycList *list, char *buffer, size_t buflen)
 {
 	size_t i, cur = 0;
 	psycString *elem;
 
-	if (list->length > buflen)
+	if (list->length > buflen) // return error if list doesn't fit in buffer
-		return PSYC_RENDER_ERROR; // return error if list doesn't fit in buffer
+		return PSYC_RENDER_LIST_ERROR;
 
 	if (list->flag == PSYC_LIST_NEED_LENGTH)
 	{
@@ -34,7 +34,7 @@ psycRenderRC psyc_renderList (psycList *list, char *buffer, size_t buflen)
 		}
 	}
 
-	return PSYC_RENDER_SUCCESS;
+	return PSYC_RENDER_LIST_SUCCESS;
 }
 
 static inline
@@ -66,8 +66,8 @@ psycRenderRC psyc_render (psycPacket *packet, char *buffer, size_t buflen)
 {
 	size_t i, cur = 0, len;
 
-	if (packet->length > buflen)
+	if (packet->length > buflen) // return error if packet doesn't fit in buffer
-		return PSYC_RENDER_ERROR; // return error if packet doesn't fit in buffer
+		return PSYC_RENDER_ERROR;
 
 	// render routing modifiers
 	for (i = 0; i < packet->routing.lines; i++)