render doc

include/psyc/parser.h

@@ -1,6 +1,6 @@
 /**
  * @file psyc/parser.h
- * @brief Interface for various psyc parser functions.
+ * @brief Interface for various PSYC parser functions.
  *
  * All parsing functions and the definitions they use are
  * defined in this file.

include/psyc/render.h

@@ -1,8 +1,37 @@
 #ifndef PSYC_RENDER_H
 # define PSYC_RENDER_H
 
-#include "syntax.h"
+/**
+ * @file psyc/render.h
+ * @brief Interface for PSYC packet rendering.
+ *
+ * All rendering functions and the definitions they use are
+ * defined in this file.
+ */
 
+/**
+ * @defgroup rendering Rendering Functions
+ *
+ * This module contains all rendering functions.
+ * @{
+ */
+
+/**
+ * Return codes for PSYC_render.
+ */
+typedef enum
+{
+	//PSYC_RENDER_ERROR_ROUTING = -2,
+	PSYC_RENDER_ERROR = -1,
+	PSYC_RENDER_SUCCESS = 0,
+} PSYC_RenderRC;
+
+/**
+ * Render a PSYC packet into a buffer.
+ */
+PSYC_RenderRC PSYC_render(PSYC_Packet *packet, char *buffer, size_t buflen);
+
+/*
 typedef enum
 {
 	PSYC_RENDER_CHECK_LENGTH = 0,
@@ -10,17 +39,12 @@ typedef enum
 	PSYC_RENDER_NO_LENGTH = 2,
 	PSYC_RENDER_ROUTING = 3,
 } PSYC_RenderFlag;
-
-typedef enum
-{
-	PSYC_RENDER_ERROR_ROUTING = -2,
-	PSYC_RENDER_ERROR = -1,
-	PSYC_RENDER_SUCCESS = 0,
-} PSYC_RenderRC;
+*/
 
 /**
  * Struct for keeping render state.
  */
+/*
 typedef struct
 {
 	PSYC_RenderFlag flag; ///< flags for the renderer
@@ -31,9 +55,7 @@ typedef struct
 	size_t length; ///< how big is the buffer we allocated
 	char buffer[]; ///< OMG a C99 feature! variable size buffer!
 } PSYC_RenderState;
-
-PSYC_RenderRC PSYC_render(PSYC_Packet *packet, char *buffer, size_t buflen);
-
+*/
 /**
  * Initiates the state struct.
  *
@@ -52,3 +74,5 @@ int PSYC_renderBody(PSYC_RenderState* render,
                     const char* data, size_t dlength);
 */
 #endif // PSYC_RENDER_H
+
+/** @} */ // end of rendering group

src/render.c

@@ -1,5 +1,6 @@
 #include "psyc/lib.h"
 #include "psyc/render.h"
+#include "psyc/syntax.h"
 
 inline size_t PSYC_renderModifier(PSYC_Modifier *m, char *buffer)
 {
@@ -28,38 +29,43 @@ PSYC_RenderRC PSYC_render(PSYC_Packet *packet, char *buffer, size_t buflen)
 	size_t i, cur = 0;
 
 	if (packet->length > buflen)
-		return PSYC_RENDER_ERROR;
+		return PSYC_RENDER_ERROR; // return error if packet doesn't fit in buffer
 
+	// render routing modifiers
 	for (i = 0; i < packet->routing.lines; i++)
 		cur += PSYC_renderModifier(&packet->routing.modifiers[i], buffer + cur);
 
+	// add length if needed
 	if (packet->flag == PSYC_PACKET_NEED_LENGTH) {
 		//cur += sprintf(buffer + cur, "%ld", packet->contentLength);
 		cur += itoa(packet->contentLength, buffer + cur, 10);
 	}
 
-	buffer[cur++] = '\n';
+	buffer[cur++] = '\n'; // start of content part
 
+	// render entity modifiers
 	for (i = 0; i < packet->entity.lines; i++)
 		cur += PSYC_renderModifier(&packet->entity.modifiers[i], buffer + cur);
 
-	if (packet->method.length)
+	if (packet->method.length) // add method\n
 	{
 		memcpy(buffer + cur, packet->method.ptr, packet->method.length);
 		cur += packet->method.length;
 		buffer[cur++] = '\n';
 	}
 
-	if (packet->data.length)
+	if (packet->data.length) // add data\n
 	{
 		memcpy(buffer + cur, packet->data.ptr, packet->method.length);
 		cur += packet->data.length;
 		buffer[cur++] = '\n';
 	}
 
+	// add packet delimiter
 	buffer[cur++] = C_GLYPH_PACKET_DELIMITER;
 	buffer[cur++] = '\n';
 
+	// actual length should be equal to pre-calculated length at this point
 	assert(cur == packet->length);
 	return PSYC_RENDER_SUCCESS;
 }