Add documentation

json.c

@@ -16,6 +16,8 @@ Json json_init(FILE* stream, Whitespace whitespace)
 
 void json_free(Json* json)
 {
+    // `json_free` just exists for symmetry with `json_init`.
+    // It does nothing, for now.
 }
 
 void begin_value(Json* json);
@@ -24,6 +26,7 @@ void push_indentation(Json* json);
 void pop_indentation(Json* json);
 void indent(Json* json);
 
+/// Begin a JSON array value.
 void json_begin_array(Json* json)
 {
     begin_value(json);
@@ -32,6 +35,7 @@ void json_begin_array(Json* json)
     json->next_punctuation = NONE;
 }
 
+/// End a JSON array value.
 void json_end_array(Json* json)
 {
     pop_indentation(json);
@@ -43,12 +47,17 @@ void json_end_array(Json* json)
         break;
     case BEGINNING:
     case COLON:
+        // The only way to get here is by either:
+        // - calling `json_end_array` right after `json_init`
+        // - calling `json_end_array` right after `json_add_object_field`
+        // - setting `next_punctuation` explicitly
         UNREACHABLE();
     }
     putc(']', json->stream);
     end_value(json);
 }
 
+/// Begin a JSON object value.
 void json_begin_object(Json* json)
 {
     begin_value(json);
@@ -57,6 +66,7 @@ void json_begin_object(Json* json)
     json->next_punctuation = NONE;
 }
 
+/// End a JSON object value.
 void json_end_object(Json* json)
 {
     pop_indentation(json);
@@ -68,12 +78,18 @@ void json_end_object(Json* json)
         break;
     case BEGINNING:
     case COLON:
+        // The only way to get here is by either:
+        // - calling `json_end_object` right after `json_init`
+        // - calling `json_end_object` right after `json_add_object_field`
+        // - settings `next_punctuation` explicitly
         UNREACHABLE();
     }
     putc('}', json->stream);
     end_value(json);
 }
 
+/// Add a JSON object field key.
+/// This should always be followed by adding a JSON value.
 void json_add_object_field(Json* json, const char* key)
 {
     begin_value(json);
@@ -81,6 +97,7 @@ void json_add_object_field(Json* json, const char* key)
     json->next_punctuation = COLON;
 }
 
+/// Add a JSON string value.
 void json_add_string(Json* json, const char* value)
 {
     begin_value(json);
@@ -88,6 +105,7 @@ void json_add_string(Json* json, const char* value)
     end_value(json);
 }
 
+/// Add a JSON long value.
 void json_add_long(Json* json, long value)
 {
     begin_value(json);
@@ -95,6 +113,7 @@ void json_add_long(Json* json, long value)
     end_value(json);
 }
 
+/// Add a JSON double value.
 void json_add_double(Json* json, double value)
 {
     begin_value(json);
@@ -102,6 +121,7 @@ void json_add_double(Json* json, double value)
     end_value(json);
 }
 
+/// Add a JSON bool value.
 void json_add_bool(Json* json, bool value)
 {
     begin_value(json);
@@ -115,6 +135,7 @@ void json_add_bool(Json* json, bool value)
     end_value(json);
 }
 
+/// Add a JSON null value
 void json_add_null(Json* json)
 {
     begin_value(json);
@@ -122,6 +143,8 @@ void json_add_null(Json* json)
     end_value(json);
 }
 
+/// Begin a new JSON value.
+/// Appends the appropriate punctuation to the stream.
 void begin_value(Json* json)
 {
     switch (json->next_punctuation) {
@@ -143,27 +166,33 @@ void begin_value(Json* json)
     }
 }
 
+/// End a JSON value.
 void end_value(Json* json)
 {
     json->next_punctuation = COMMA;
 }
 
+/// Increment the indent level by one.
 void push_indentation(Json* json)
 {
     json->indent_level += 1;
 }
 
+/// Decrement the indent level by one.
 void pop_indentation(Json* json)
 {
     json->indent_level -= 1;
 }
 
+/// Append a newline and whitespace for the next line,
+/// except when `whitespace` is set to `MINIFIED`.
 void indent(Json* json)
 {
     char indent_char = ' ';
     int n;
     switch (json->whitespace) {
     case MINIFIED:
+        // In minified mode, we don't want newlines or whitespace.
         return;
     case INDENT_1:
         n = 1 * json->indent_level;
@@ -185,6 +214,7 @@ void indent(Json* json)
         n = json->indent_level;
         break;
     }
+
     putc('\n', json->stream);
     for (int i = 0; i < n; i++) {
         putc(indent_char, json->stream);