review remarks

Author: RadWolfie

include/libParamTypes.h

@@ -2,8 +2,8 @@
 
 PARAM_TYPE_32(unk)  // Unknown, intended to be used for "not a function" types and for "function" documentation when reverse-engineering efforts could not narrow it down to either the stack or one of the registers.
 PARAM_TYPE__0(void) //  0 bits
-PARAM_TYPE_64(stk2) // 64 bits
-PARAM_TYPE_32(stk)  // 32 bits
+PARAM_TYPE_64(stk2) // 64 bits (two pushes)
+PARAM_TYPE_32(stk)  // 32 bits (one push)
 PARAM_TYPE_32(eax)  // 32 bits
 PARAM_TYPE_16_(ax)  // 16 bits
 PARAM_TYPE__8_(ah)  //  8 bits

include/libXbSymbolDatabase.h

@@ -230,7 +230,7 @@ void XbSymbolDatabase_SetOutputMessage(xb_output_message_t message_func);
 
 /// <summary>
 /// To register any detected symbol name with address and build version back to third-party program.
-/// NOTE: Be aware of library name will be variety since some libraries are detecting in other sections as well.
+/// NOTE: Be aware that the library name will vary since some libraries are detected in other sections as well.
 /// </summary>
 /// <param name="library_str">Name of the library in string.</param>
 /// <param name="library_flag">Name of the library in flag.</param>

include/xref/list_xref.h

@@ -422,8 +422,8 @@ typedef enum _XRefDatabase {
     // Also, if XREF_COUNT > sizeof(uint16), enlarge struct OOVPA.XRefSaveIndex (and Value somehow)
 } XRefDatabase;
 
-// NOTE: XREF_PUBLIC_INDEX is only for library's internal API usage.
-#define XREF_PUBLIC_INDEX(xref_index) xref_index - XREF_KT_COUNT - 1
+#define XREF_API_TO_PUBLIC_INDEX(xref_api_index)    xref_api_index - XREF_KT_COUNT - 1
+#define XREF_PUBLIC_TO_API_INDEX(xref_public_index) xref_public_index + XREF_KT_COUNT + 1
 
 #define XREF_ADDR_UNDETERMINED -1
 #define XREF_ADDR_NOT_FOUND    ((void*)0)

src/OOVPADatabase/OOVPA.h

@@ -31,7 +31,7 @@
 // MSVC_EXPAND works around a Visual C++ problem, expanding __VA_ARGS__ incorrectly:
 #define MSVC_EXPAND(x) x
 
-// Wrap C++ style macro function for clang-format to follow our code style.
+// Wrap C++ style macro function so that clang-format follows our code style.
 // NOTE: Not relative to MSVC_EXPAND macro's bugfix.
 #define MACRO_FUNC(x) x
 
@@ -46,10 +46,10 @@
 #define UNPARENTHESES_INVOKE(args) VA_ARGS_EXPAND(args)
 #define UNPARENTHESES(args)        UNPARENTHESES_INVOKE(VA_ARGS_EXPAND args)
 
-// count array type size
+// get the number of elements of an array
 #define COUNT_ARRAYSIZE(type_, array_) (sizeof((type_[])UNPARENTHESES(array_)) / sizeof(type_))
 
-// Increment counter for PARAMS macro to use with.
+// Increment counter used by the PARAMS macro.
 #define INC_1  2
 #define INC_2  3
 #define INC_3  4
@@ -211,7 +211,7 @@ typedef struct _LOOVPA {
 
 #define OOVPA_END }
 
-#pragma pack() // require restore pack for AppleClang to build
+#pragma pack() // restore packing so that AppleClang can build
 typedef struct _OOVPARevision {
     OOVPA* Oovpa;
     unsigned short Version; // : 13; // 2^13 = 8192, enough to store lowest and highest possible Library Version number in
@@ -229,7 +229,7 @@ typedef enum _eDBScanType {
 // ******************************************************************
 // * OOVPATable
 // ******************************************************************
-#pragma pack() // require restore pack for AppleClang to build
+#pragma pack() // restore packing so that AppleClang can build
 typedef struct _OOVPATable {
     const uint16_t xref;
     const unsigned scan_type;
@@ -299,13 +299,13 @@ typedef struct _OOVPATable {
 #define CALL_fas   call_fastcall
 #define CALL(Name) CALL_##Name
 
-// For generate symbol's suffix name, mainly for registers, and extend API usage.
+// For generate symbol's suffix name, mainly for registers, and extended API usage.
 #define PARAM(Param, Name)            Param, Name
 #define PARAM1(Param)                 Param, ""
 #define PARAM_TOKEN_unk(Index, Name)  _unk##Index
 #define PARAM_TOKEN_void(Index, Name) // No argument, do not append to symbol reference.
-#define PARAM_TOKEN_stk2(Index, Name) // Argument is stored in call stack, do not append to symbol reference.
-#define PARAM_TOKEN_stk(Index, Name)  // Argument is stored in call stack, do not append to symbol reference.
+#define PARAM_TOKEN_stk2(Index, Name) // (Custom) argument is stored in call stack with two pushes, do not append to symbol reference.
+#define PARAM_TOKEN_stk(Index, Name)  // Argument is stored in call stack with one push, do not append to symbol reference.
 #define PARAM_TOKEN_eax(Index, Name)  _eax##Index
 #define PARAM_TOKEN__ax(Index, Name)  _ax##Index
 #define PARAM_TOKEN__ah(Index, Name)  _ah##Index

src/lib/libXbSymbolDatabase.c

@@ -444,7 +444,7 @@ const char* XbSymbolDatabase_SymbolReferenceToString(uint32_t xref_index)
     if (xref_index <= XREF_KT_COUNT || XREF_COUNT <= xref_index) {
         return NULL;
     }
-    return xref_str[XREF_PUBLIC_INDEX(xref_index)];
+    return xref_str[XREF_API_TO_PUBLIC_INDEX(xref_index)];
 }
 
 // NOTE: Library string must return only one specific flag, cannot make a mix combo flags.