docs: fix documentation errors, typos and improve API clarity

Author: ProjectSky

extensions/yyjson/IYYJSONManager.h

@@ -5,6 +5,7 @@
 
 using SourceMod::Handle_t;
 using SourceMod::HandleType_t;
+using SourceMod::SMInterface;
 using SourcePawn::IPluginContext;
 
 // Forward declaration
@@ -27,7 +28,7 @@ enum YYJSON_SORT_ORDER
 
 /**
  * @brief Parameter provider interface for Pack operation
- *
+ * 
  * Allows Pack to retrieve parameters in a platform-independent way.
  */
 class IPackParamProvider
@@ -56,7 +57,7 @@ class IPackParamProvider
  *     SM_GET_LATE_IFACE(YYJSONMANAGER, g_pYYJSONManager);
  * }
  */
-class IYYJSONManager : public SourceMod::SMInterface
+class IYYJSONManager : public SMInterface
 {
 public:
 	virtual const char *GetInterfaceName() override {
@@ -87,8 +88,11 @@ class IYYJSONManager : public SourceMod::SMInterface
 	 * @param buffer Output buffer
 	 * @param buffer_size Buffer size
 	 * @param write_flg Write flags (YYJSON_WRITE_FLAG values, default: 0)
-	 * @param out_size Pointer to receive actual size (optional, default: nullptr)
-	 * @return true on success
+	 * @param out_size Pointer to receive actual size written (including null terminator), optional
+	 * @return true on success, false if buffer is too small or on error
+	 * 
+	 * @note The out_size parameter returns the size including null terminator
+	 * @note Use GetSerializedSize() with the same write_flg to determine buffer size
 	 */
 	virtual bool WriteToString(YYJSONValue* handle, char* buffer, size_t buffer_size, 
 		uint32_t write_flg = 0, size_t* out_size = nullptr) = 0;
@@ -126,15 +130,28 @@ class IYYJSONManager : public SourceMod::SMInterface
 	/**
 	 * Get human-readable type description string
 	 * @param handle JSON value
-	 * @return Type description string (e.g., "object", "array", "string", "number", "true", "false", "null")
+	 * @return Type description string (e.g., "object", "array", "string", "number", "true", "false", "unknown")
 	 */
 	virtual const char* GetTypeDesc(YYJSONValue* handle) = 0;
 
 	/**
 	 * Get the size needed to serialize this JSON value
+	 * 
 	 * @param handle JSON value
 	 * @param write_flg Write flags (YYJSON_WRITE_FLAG values, default: 0)
 	 * @return Size in bytes (including null terminator)
+	 * 
+	 * @note The returned size depends on the write_flg parameter.
+	 *       You MUST use the same flags when calling both GetSerializedSize() 
+	 *       and WriteToString(). Using different flags will return 
+	 *       different sizes and may cause buffer overflow.
+	 * 
+	 * @example
+	 *   // Correct usage:
+	 *   auto flags = YYJSON_WRITE_PRETTY;
+	 *   size_t size = g_pYYJSONManager->GetSerializedSize(handle, flags);
+	 *   char* buffer = new char[size];
+	 *   g_pYYJSONManager->WriteToString(handle, buffer, size, flags);  // Use same flags
 	 */
 	virtual size_t GetSerializedSize(YYJSONValue* handle, uint32_t write_flg = 0) = 0;
 
@@ -278,7 +295,11 @@ class IYYJSONManager : public SourceMod::SMInterface
 	/**
 	 * Get the number of bytes read when parsing this document
 	 * @param handle JSON value
-	 * @return Number of bytes read during parsing, 0 if not from parsing
+	 * @return Number of bytes read during parsing (excluding null terminator), 0 if not from parsing
+	 * 
+	 * @note This value only applies to documents created from parsing
+	 * @note Manually created documents (ObjectInit, CreateBool, etc.) will return 0
+	 * @note The returned size does not include the null terminator
 	 */
 	virtual size_t GetReadSize(YYJSONValue* handle) = 0;
 

extensions/yyjson/YYJSONManager.cpp

@@ -527,7 +527,12 @@ size_t YYJSONManager::GetReadSize(YYJSONValue* handle)
 		return 0;
 	}
 
-	return handle->m_readSize;
+	// this not happen in normal case, but it's possible if the document is not from parsing.
+	if (handle->m_readSize == 0) {
+		return 0;
+	}
+
+	return handle->m_readSize + 1;
 }
 
 YYJSONValue* YYJSONManager::ObjectInit()

extensions/yyjson/YYJSONManager.h

@@ -61,7 +61,7 @@ class YYJSONValue {
 	yyjson_obj_iter m_iterObjImm;
 	yyjson_arr_iter m_iterArrImm;
 
-	SourceMod::Handle_t m_handle{ BAD_HANDLE };
+	Handle_t m_handle{ BAD_HANDLE };
 	size_t m_arrayIndex{ 0 };
 	size_t m_readSize{ 0 };
 	bool m_iterInitialized{ false };

extensions/yyjson/extension.cpp

@@ -54,9 +54,4 @@ void JsonExtension::SDK_OnUnload()
 void JSONHandler::OnHandleDestroy(HandleType_t type, void* object)
 {
 	delete (YYJSONValue*)object;
-}
-
-IYYJSONManager* JsonExtension::GetYYJSONManager()
-{
-	return g_pYYJSONManager;
 }

extensions/yyjson/extension.h

@@ -11,7 +11,6 @@ class JsonExtension : public SDKExtension
 public:
 	virtual bool SDK_OnLoad(char *error, size_t maxlength, bool late);
 	virtual void SDK_OnUnload();
-	IYYJSONManager* GetYYJSONManager();
 };
 
 class JSONHandler : public IHandleTypeDispatch

extensions/yyjson/json_natives.cpp

@@ -669,7 +669,7 @@ static cell_t json_val_get_read_size(IPluginContext* pContext, const cell_t* par
 	size_t size = g_pYYJSONManager->GetReadSize(handle);
 	if (size == 0) return 0;
 
-	return static_cast<cell_t>(size + 1);
+	return static_cast<cell_t>(size);
 }
 
 static cell_t json_val_create_null(IPluginContext* pContext, const cell_t* params)

plugins/include/yyjson.inc

@@ -198,7 +198,7 @@ methodmap YYJSON < Handle
   * @param maxlength         Maximum length of the string buffer
   * @param flag              The JSON write options
   *
-  * @return                  Number of characters written to the buffer, including the null terminator. 0 on failure
+  * @return                  Number of characters written to the buffer (including null terminator) or 0 on failure
   */
   public native int ToString(char[] buffer, int maxlength, YYJSON_WRITE_FLAG flag = YYJSON_WRITE_NOFLAG);
 
@@ -278,7 +278,7 @@ methodmap YYJSON < Handle
   public static native YYJSON CreateFloat(float value);
 
   /**
-  * Creates and returns a int value
+  * Creates and returns an int value
   *
   * @note                    Needs to be freed using delete or CloseHandle()
   *
@@ -289,11 +289,11 @@ methodmap YYJSON < Handle
   public static native YYJSON CreateInt(int value);
 
   /**
-  * Creates and returns a intger64 value
+  * Creates and returns an integer64 value
   *
   * @note                    Needs to be freed using delete or CloseHandle()
   *
-  * @param value             The intger64 value to be set
+  * @param value             The integer64 value to be set
   *
   * @return                  JSON handle, NULL on error
   */
@@ -347,7 +347,7 @@ methodmap YYJSON < Handle
   public static native int GetInt(const YYJSON value);
 
   /**
-  * Get intger64 value by a JSON Handle
+  * Get integer64 value by a JSON Handle
   *
   * @param value             JSON handle
   * @param buffer            Buffer to copy to
@@ -369,12 +369,17 @@ methodmap YYJSON < Handle
   public static native bool GetString(const YYJSON value, char[] buffer, int maxlength);
 
   /**
-  * Get JSON Handle serialized size in bytes (including null-terminator)
-  *
-  * @param flag              The JSON write options
-  *
-  * @return                  serialized size
-  */
+   * Get JSON Handle serialized size in bytes (including null-terminator)
+   *
+   * @param flag              The JSON write options
+   *
+   * @return                  Size in bytes (including null terminator)
+   * 
+   * @note                    The returned size depends on the flag parameter.
+   *                          You MUST use the same flags when calling both GetSerializedSize() 
+   *                          and ToString(). Using different flags will return different sizes 
+   *                          and may cause buffer overflow.
+   */
   public native int GetSerializedSize(YYJSON_WRITE_FLAG flag = YYJSON_WRITE_NOFLAG);
 
   /**
@@ -435,7 +440,7 @@ methodmap YYJSON < Handle
   *
   * @return                  True on success, false on failure
   */
-  public native bool PtrGetString(const char[] path, char[] buffer, int maxlength)
+  public native bool PtrGetString(const char[] path, char[] buffer, int maxlength);
 
   /**
   * Get value is null by a JSON Pointer
@@ -444,26 +449,28 @@ methodmap YYJSON < Handle
   *
   * @return                  True if the value is null, false otherwise
   */
-  public native bool PtrGetIsNull(const char[] path)
+  public native bool PtrGetIsNull(const char[] path);
 
   /**
   * Get JSON content length (string length, array size, object size)
-  * Returns 0 if val is NULL or type is not string/array/object
-  * if str including null-terminator
+  *
+  * @note                    For strings: returns string length including null-terminator
+  * @note                    For arrays/objects: returns number of elements
+  * @note                    Returns 0 if value is NULL or type is not string/array/object
   *
   * @param path              The JSON pointer string
   *
   * @return                  JSON content length
   */
-  public native int PtrGetLength(const char[] path)
+  public native int PtrGetLength(const char[] path);
 
   /**
   * Set value by a JSON Pointer
   *
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The value to be set, pass NULL to remove
+  * @param value             The value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -475,7 +482,7 @@ methodmap YYJSON < Handle
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The boolean value to be set, pass NULL to remove
+  * @param value             The boolean value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -487,7 +494,7 @@ methodmap YYJSON < Handle
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The float value to be set, pass NULL to remove
+  * @param value             The float value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -499,19 +506,19 @@ methodmap YYJSON < Handle
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The integer value to be set, pass NULL to remove
+  * @param value             The integer value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
   public native bool PtrSetInt(const char[] path, int value);
 
   /**
-  * Set intger64 value by a JSON Pointer
+  * Set integer64 value by a JSON Pointer
   *
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The intger64 value to be set, pass NULL to remove
+  * @param value             The integer64 value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -523,7 +530,7 @@ methodmap YYJSON < Handle
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The string value to be set, pass NULL to remove
+  * @param value             The string value to be set
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -535,7 +542,6 @@ methodmap YYJSON < Handle
   * @note                    The parent nodes will be created if they do not exist. If the target value already exists, it will be replaced by the new value
   *
   * @param path              The JSON pointer string
-  * @param value             The null value to be set, pass NULL to remove
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -585,7 +591,7 @@ methodmap YYJSON < Handle
   * Add (insert) integer64 value by a JSON pointer
   *
   * @param path              The JSON pointer string
-  * @param value             The intger64 value to be added
+  * @param value             The integer64 value to be added
   *
   * @return                  true if JSON pointer is valid and new value is set, false otherwise
   */
@@ -617,7 +623,7 @@ methodmap YYJSON < Handle
   *
   * @return                  true if removed value, false otherwise
   */
-  public native bool PtrRemove(const char[] path)
+  public native bool PtrRemove(const char[] path);
 
   /**
   * Try to get value by a JSON Pointer
@@ -801,14 +807,16 @@ methodmap YYJSON < Handle
   }
 
   /**
-  * Retrieves read size of the JSON data
+  * Retrieves the size of the JSON data as it was originally read from parsing
   *
-  * @note This value reflects the size of the JSON data as read from the document
-  *       - It does not auto update if the document is modified
-  *       - For modified document, use GetSerializedSize to obtain the current size
+  * @return                  Size in bytes (including null terminator) or 0 if not from parsing
   *
+  * @note                    This value only applies to documents created from parsing (Parse, FromString, FromFile)
+  * @note                    Manually created documents (new YYJSONObject(), YYJSON.CreateBool(), etc.) will return 0
+  * @note                    This value does not auto-update if the document is modified
+  * @note                    For modified documents, use GetSerializedSize() to obtain the current size
   */
-  property bool ReadSize {
+  property int ReadSize {
     public native get();
   }
 };
@@ -1219,7 +1227,7 @@ methodmap YYJSONArray < YYJSON
   public native bool SetFloat(int index, float value);
 
   /**
-  * Replaces a integer value at index
+  * Replaces an integer value at index
   *
   * @param index             The index to which to replace the value
   * @param value             The new int value to replace
@@ -1229,10 +1237,10 @@ methodmap YYJSONArray < YYJSON
   public native bool SetInt(int index, int value);
 
   /**
-  * Replaces a intger64 value at index
+  * Replaces an integer64 value at index
   *
   * @param index             The index to which to replace the value
-  * @param value             The new intger64 value to replace
+  * @param value             The new integer64 value to replace
   *
   * @return                  True if succeed, false otherwise
   */
@@ -1285,7 +1293,7 @@ methodmap YYJSONArray < YYJSON
   public native bool PushFloat(float value);
 
   /**
-  * Inserts a integer value at the end of the array
+  * Inserts an integer value at the end of the array
   *
   * @param value             integer to set
   *
@@ -1294,9 +1302,9 @@ methodmap YYJSONArray < YYJSON
   public native bool PushInt(int value);
 
   /**
-  * Inserts a intger64 value at the end of the array
+  * Inserts an integer64 value at the end of the array
   *
-  * @param value             intger64 value
+  * @param value             integer64 value
   *
   * @return                  The value to be inserted. Returns false if it is NULL
   */