From 07bf50cf9a177c10b2f6acaf116d0fea4428e3b8 Mon Sep 17 00:00:00 2001
From: antares <antares@alyr.dev>
Date: Tue, 26 Nov 2024 01:52:24 +0800
Subject: [PATCH] Add doc, remove old macros

---
 src/encode/encode_impl.c | 29 ++++++++++++++++++++++++++---
 src/pyyjson_config.h     | 22 ++--------------------
 2 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/src/encode/encode_impl.c b/src/encode/encode_impl.c
index b2f092e..cfbeeb5 100644
--- a/src/encode/encode_impl.c
+++ b/src/encode/encode_impl.c
@@ -789,17 +789,39 @@ force_inline bool vec_in_boundary(UnicodeVector *vec) {
 
 /* 
  * Some utility functions only related to *write*, like vector reserve, writing number
- * need macro: COMPILE_WRITE_UCS_LEVEL, value: 1, 2, or 4
+ * need macro: COMPILE_WRITE_UCS_LEVEL, value: 1, 2, or 4.
  */
 #include "encode_utils_impl_wrap.inl"
 
+/* 
+ * Some utility functions related to SIMD, like getting escape mask,
+ * elevating ucs level, read/write simd vars.
+ * need macro:
+ *      COMPILE_READ_UCS_LEVEL, value: 1, 2, or 4.
+ *      COMPILE_WRITE_UCS_LEVEL, value: 1, 2, or 4.
+ */
 #include "encode_simd_utils_wrap.inl"
 
+/* 
+ * Some functions for writing the unicode vector, like writing key, writing value str.
+ * need macro:
+ *      COMPILE_READ_UCS_LEVEL, value: 1, 2, or 4.
+ *      COMPILE_WRITE_UCS_LEVEL, value: 1, 2, or 4.
+ */
 #include "encode_unicode_impl_wrap.inl"
 
+/* 
+ * Top-level encode functions, like encode list, encode dict, encode single unicode.
+ * need macro:
+ *      COMPILE_UCS_LEVEL, value: 0, 1, 2, or 4. COMPILE_UCS_LEVEL is the current writing level.
+ *          This differs from COMPILE_WRITE_UCS_LEVEL: `0` stands for ascii. Since we always start from
+ *          writing ascii, `0` also defines the entrance of encoding. See `PYYJSON_DUMPS_OBJ` for more
+ *          details.
+ *      COMPILE_INDENT_LEVEL, value: 0, 2, or 4.
+ */
 #include "encode_impl_wrap.inl"
 
-
+/* Encodes non-container types. */
 force_inline PyObject *pyyjson_dumps_single_unicode(PyObject *unicode) {
     UnicodeVector *vec = PyObject_Malloc(PYYJSON_ENCODE_DST_BUFFER_INIT_SIZE);
     RETURN_ON_UNLIKELY_ERR(!vec);
@@ -812,7 +834,7 @@ force_inline PyObject *pyyjson_dumps_single_unicode(PyObject *unicode) {
         U8_WRITER(vec) = (u8 *) (((PyCompactUnicodeObject *) vec) + 1);
     }
     void *write_start = (void *) U8_WRITER(vec);
-    vec->head.write_end = (void *) ((u8 *) vec + PYYJSON_ENCODE_DST_BUFFER_INIT_SIZE);
+    vec->head.write_end = (void *) (((u8 *) vec) + PYYJSON_ENCODE_DST_BUFFER_INIT_SIZE);
     bool success;
     switch (unicode_kind) {
         // pass `is_in_obj = true` to avoid unwanted indent check
@@ -902,6 +924,7 @@ force_inline PyObject *pyyjson_dumps_single_float(PyObject *val) {
     return unicode;
 }
 
+/* Entrance for python code. */
 force_noinline PyObject *pyyjson_Encode(PyObject *self, PyObject *args, PyObject *kwargs) {
     PyObject *obj;
     int option_digit = 0;
diff --git a/src/pyyjson_config.h b/src/pyyjson_config.h
index e00a5a6..85b4cf8 100644
--- a/src/pyyjson_config.h
+++ b/src/pyyjson_config.h
@@ -27,10 +27,12 @@
 #ifndef PYYJSON_STRING_BUFFER_SIZE
 #define PYYJSON_STRING_BUFFER_SIZE (512 * 1024)
 #endif
+
 /* Buffer for key associative cache. Default cost: 2048 * sizeof(pyyjson_cache_type) = 16kb (per thread). */
 #ifndef PYYJSON_KEY_CACHE_SIZE
 #define PYYJSON_KEY_CACHE_SIZE (1 << 11)
 #endif
+
 /* Stack buffer for PyObject*. Default cost: 8 * 1024 = 8kb (per thread). */
 #ifndef PYYJSON_OBJSTACK_BUFFER_SIZE
 #define PYYJSON_OBJSTACK_BUFFER_SIZE (1024)
@@ -44,14 +46,6 @@
 #define PYYJSON_ENCODE_DST_BUFFER_INIT_SIZE (1024)
 #endif
 
-/*
- Init buffer size for op buffer.
- Cost: PYYJSON_ENCODE_OP_BUFFER_INIT_SIZE * sizeof(void*) bytes per thread.
- */
-#ifndef PYYJSON_ENCODE_OP_BUFFER_INIT_SIZE
-#define PYYJSON_ENCODE_OP_BUFFER_INIT_SIZE (1024)
-#endif
-
 /*
  Max nested structures for encoding.
  Cost: PYYJSON_ENCODE_MAX_RECURSION * sizeof(void*) * 2 bytes per thread.
@@ -60,18 +54,6 @@
 #define PYYJSON_ENCODE_MAX_RECURSION (1024)
 #endif
 
-#ifndef PYYJSON_ENCODE_ADDR_DESC_BUFFER_INIT_SIZE
-#define PYYJSON_ENCODE_ADDR_DESC_BUFFER_INIT_SIZE ((Py_ssize_t)1 << 14)
-#endif
-
-#ifndef PYYJSON_ENCODE_OBJ_VIEW_BUFFER_INIT_SIZE
-#define PYYJSON_ENCODE_OBJ_VIEW_BUFFER_INIT_SIZE ((Py_ssize_t)1 << 14)
-#endif
-
-#ifndef PYYJSON_ENCODE_VIEW_DATA_BUFFER_INIT_SIZE
-#define PYYJSON_ENCODE_VIEW_DATA_BUFFER_INIT_SIZE ((Py_ssize_t)1 << 14)
-#endif
-
 /*
  When a character needs escape when encoding,
  the following `PYYJSON_ENCODE_ESCAPE_ONCE_BYTES`