♻️ Document variables in stores.cpp

This also fixes OOB when buying all items in a list

Source/items.cpp

@@ -1292,6 +1292,11 @@ void GetPlrHandSeed(ItemStruct *h)
 	h->_iSeed = AdvanceRndSeed();
 }
 
+/**
+ * @brief Set a new unique seed value on the given item
+ * @param pnum Player id
+ * @param h Item to update
+ */
 void GetGoldSeed(int pnum, ItemStruct *h)
 {
 	int i, ii, s;

Source/stores.h

@@ -14,6 +14,33 @@ DEVILUTION_BEGIN_NAMESPACE
 extern "C" {
 #endif
 
+typedef enum talk_id {
+	STORE_NONE,
+	STORE_SMITH,
+	STORE_SBUY,
+	STORE_SSELL,
+	STORE_SREPAIR,
+	STORE_WITCH,
+	STORE_WBUY,
+	STORE_WSELL,
+	STORE_WRECHARGE,
+	STORE_NOMONEY,
+	STORE_NOROOM,
+	STORE_CONFIRM,
+	STORE_BOY,
+	STORE_BBOY,
+	STORE_HEALER,
+	STORE_STORY,
+	STORE_HBUY,
+	STORE_SIDENTIFY,
+	STORE_SPBUY,
+	STORE_GOSSIP,
+	STORE_IDSHOW,
+	STORE_TAVERN,
+	STORE_DRUNK,
+	STORE_BARMAID,
+} talk_id;
+
 typedef struct STextStruct {
 	int _sx;
 	int _syoff;
@@ -25,29 +52,48 @@ typedef struct STextStruct {
 	int _sval;
 } STextStruct;
 
-extern ItemStruct boyitem;
-extern ItemStruct premiumitem[SMITH_PREMIUM_ITEMS];
+/** Shop frame graphics */
 extern BYTE *pSTextBoxCels;
-extern int premiumlevel;
-extern ItemStruct witchitem[WITCH_ITEMS];
+/** Small text selection cursor */
+extern BYTE *pSPentSpn2Cels;
+/** Scrollbar graphics */
+extern BYTE *pSTextSlidCels;
+
+/** Currently active store */
+extern talk_id stextflag;
+
+/** Temporary item used to generate gold piles by various function */
+extern ItemStruct golditem;
+
+/** Items sold by Griswold */
+extern ItemStruct smithitem[SMITH_ITEMS];
+/** Number of premium items for sale by Griswold */
 extern int numpremium;
+/** Base level of current premium items sold by Griswold */
+extern int premiumlevel;
+/** Premium items sold by Griswold */
+extern ItemStruct premiumitem[SMITH_PREMIUM_ITEMS];
+
+/** Items sold by Pepin */
 extern ItemStruct healitem[20];
-extern ItemStruct golditem;
-extern BYTE *pSTextSlidCels;
-extern BYTE *pSPentSpn2Cels;
+
+/** Items sold by Adria */
+extern ItemStruct witchitem[WITCH_ITEMS];
+
+/** Current level of the item sold by Wirt */
 extern int boylevel;
-extern ItemStruct smithitem[SMITH_ITEMS];
-extern char stextflag;
+/** Current item sold by Wirt */
+extern ItemStruct boyitem;
 
 void InitStores();
 int PentSpn2Spin();
 void SetupTownStores();
 void FreeStoreMem();
-void PrintSString(CelOutputBuffer out, int x, int y, BOOL cjustflag, const char *str, char col, int val);
+void PrintSString(CelOutputBuffer out, int x, int y, bool cjustflag, const char *str, char col, int val);
 void DrawSLine(int y);
 void DrawSTextHelp();
 void ClearSText(int s, int e);
-void StartStore(char s);
+void StartStore(talk_id s);
 void DrawSText(CelOutputBuffer out);
 void STextESC();
 void STextUp();

enums.h

@@ -2393,33 +2393,6 @@ typedef enum quest_mush_state {
 	QS_BRAINGIVEN   = 7,
 } quest_mush_state;
 
-typedef enum talk_id {
-	STORE_NONE      = 0x0,
-	STORE_SMITH     = 0x1,
-	STORE_SBUY      = 0x2,
-	STORE_SSELL     = 0x3,
-	STORE_SREPAIR   = 0x4,
-	STORE_WITCH     = 0x5,
-	STORE_WBUY      = 0x6,
-	STORE_WSELL     = 0x7,
-	STORE_WRECHARGE = 0x8,
-	STORE_NOMONEY   = 0x9,
-	STORE_NOROOM    = 0xA,
-	STORE_CONFIRM   = 0xB,
-	STORE_BOY       = 0xC,
-	STORE_BBOY      = 0xD,
-	STORE_HEALER    = 0xE,
-	STORE_STORY     = 0xF,
-	STORE_HBUY      = 0x10,
-	STORE_SIDENTIFY = 0x11,
-	STORE_SPBUY     = 0x12,
-	STORE_GOSSIP    = 0x13,
-	STORE_IDSHOW    = 0x14,
-	STORE_TAVERN    = 0x15,
-	STORE_DRUNK     = 0x16,
-	STORE_BARMAID   = 0x17,
-} talk_id;
-
 typedef enum _unique_items {
 	UITEM_CLEAVER      = 0x0,
 	UITEM_SKCROWN      = 0x1,