Account: add more docs. more clarity of arguments. fix payday proc if free (#70206)

code/modules/economy/account.dm

@@ -79,32 +79,39 @@
 
 /**
  * Performs the math component of adjusting a bank account balance.
+ * Arguments:
+ * * amount - the quantity of credits that will be written off if the value is negative, or added if it is positive.
  */
-/datum/bank_account/proc/_adjust_money(amt)
-	account_balance += amt
+/datum/bank_account/proc/_adjust_money(amount)
+	account_balance += amount
 	if(account_balance < 0)
 		account_balance = 0
 
 /**
  * Returns TRUE if a bank account has more than or equal to the amount, amt.
  * Otherwise returns false.
+ * Arguments:
+ * * amount - the quantity of credits that will be reconciled with the account balance.
  */
-/datum/bank_account/proc/has_money(amt)
-	return account_balance >= amt
+/datum/bank_account/proc/has_money(amount)
+	return account_balance >= amount
 
 /**
  * Adjusts the balance of a bank_account as well as sanitizes the numerical input.
+ * Arguments:
+ * * amount - the quantity of credits that will be written off if the value is negative, or added if it is positive.
  */
-/datum/bank_account/proc/adjust_money(amt)
-	if((amt < 0 && has_money(-amt)) || amt > 0)
-		_adjust_money(amt)
+/datum/bank_account/proc/adjust_money(amount)
+	if((amount < 0 && has_money(-amount)) || amount > 0)
+		_adjust_money(amount)
 		return TRUE
 	return FALSE
 
 /**
  * Performs a transfer of credits to the bank_account datum from another bank account.
- * *datum/bank_account/from: The bank account that is sending the credits to this bank_account datum.
- * *amount: the quantity of credits that are being moved between bank_account datums.
+ * Arguments:
+ * * datum/bank_account/from - The bank account that is sending the credits to this bank_account datum.
+ * * amount - the quantity of credits that are being moved between bank_account datums.
  */
 /datum/bank_account/proc/transfer_money(datum/bank_account/from, amount)
 	if(from.has_money(amount))
@@ -118,22 +125,26 @@
 /**
  * This proc handles passive income gain for players, using their job's paycheck value.
  * Funds are taken from the parent department account to hand out to players. This can result in payment brown-outs if too many people are in one department.
+ * Arguments:
+ * * amount_of_paychecks - literally the number of salaries, 1 for issuing one salary, 5 for issuing five salaries.
+ * * free - issuance of free funds, if TRUE then takes funds from the void, if FALSE (default) tries to send from the department's account.
  */
-/datum/bank_account/proc/payday(amt_of_paychecks, free = FALSE)
+/datum/bank_account/proc/payday(amount_of_paychecks, free = FALSE)
 	if(!account_job)
 		return
-	var/money_to_transfer = round(account_job.paycheck * payday_modifier * amt_of_paychecks)
-	if(amt_of_paychecks == 1)
+	var/money_to_transfer = round(account_job.paycheck * payday_modifier * amount_of_paychecks)
+	if(amount_of_paychecks == 1)
 		money_to_transfer = clamp(money_to_transfer, 0, PAYCHECK_CREW) //We want to limit single, passive paychecks to regular crew income.
 	if(free)
 		adjust_money(money_to_transfer)
 		SSblackbox.record_feedback("amount", "free_income", money_to_transfer)
 		SSeconomy.station_target += money_to_transfer
 		log_econ("[money_to_transfer] credits were given to [src.account_holder]'s account from income.")
+		return TRUE
 	else
-		var/datum/bank_account/D = SSeconomy.get_dep_account(account_job.paycheck_department)
-		if(D)
-			if(!transfer_money(D, money_to_transfer))
+		var/datum/bank_account/department_account = SSeconomy.get_dep_account(account_job.paycheck_department)
+		if(department_account)
+			if(!transfer_money(department_account, money_to_transfer))
 				bank_card_talk("ERROR: Payday aborted, departmental funds insufficient.")
 				return FALSE
 			else
@@ -145,16 +156,19 @@
 /**
  * This sends a local chat message to the owner of a bank account, on all ID cards registered to the bank_account.
  * If not held, sends out a message to all nearby players.
+ * Arguments:
+ * * message - text that will be sent to listeners after the id card icon 
+ * * force - if TRUE ignore checks on client and client prefernces.
  */
 /datum/bank_account/proc/bank_card_talk(message, force)
 	if(!message || !bank_cards.len)
 		return
-	for(var/obj/A in bank_cards)
-		var/icon_source = A
-		if(isidcard(A))
-			var/obj/item/card/id/id_card = A
+	for(var/obj/card in bank_cards)
+		var/icon_source = card
+		if(isidcard(card))
+			var/obj/item/card/id/id_card = card
 			icon_source = id_card.get_cached_flat_icon()
-		var/mob/card_holder = recursive_loc_check(A, /mob)
+		var/mob/card_holder = recursive_loc_check(card, /mob)
 		if(ismob(card_holder)) //If on a mob
 			if(!card_holder.client || (!(card_holder.client.prefs.chat_toggles & CHAT_BANKCARD) && !force))
 				return
@@ -162,24 +176,24 @@
 			if(card_holder.can_hear())
 				card_holder.playsound_local(get_turf(card_holder), 'sound/machines/twobeep_high.ogg', 50, TRUE)
 				to_chat(card_holder, "[icon2html(icon_source, card_holder)] [span_notice("[message]")]")
-		else if(isturf(A.loc)) //If on the ground
-			var/turf/T = A.loc
-			for(var/mob/M in hearers(1,T))
-				if(!M.client || (!(M.client.prefs.chat_toggles & CHAT_BANKCARD) && !force))
+		else if(isturf(card.loc)) //If on the ground
+			var/turf/card_location = card.loc
+			for(var/mob/potential_hearer in hearers(1,card_location))
+				if(!potential_hearer.client || (!(potential_hearer.client.prefs.chat_toggles & CHAT_BANKCARD) && !force))
 					continue
-				if(M.can_hear())
-					M.playsound_local(T, 'sound/machines/twobeep_high.ogg', 50, TRUE)
-					to_chat(M, "[icon2html(icon_source, M)] [span_notice("[message]")]")
+				if(potential_hearer.can_hear())
+					potential_hearer.playsound_local(card_location, 'sound/machines/twobeep_high.ogg', 50, TRUE)
+					to_chat(potential_hearer, "[icon2html(icon_source, potential_hearer)] [span_notice("[message]")]")
 		else
 			var/atom/sound_atom
-			for(var/mob/M in A.loc) //If inside a container with other mobs (e.g. locker)
-				if(!M.client || (!(M.client.prefs.chat_toggles & CHAT_BANKCARD) && !force))
+			for(var/mob/potential_hearer in card.loc) //If inside a container with other mobs (e.g. locker)
+				if(!potential_hearer.client || (!(potential_hearer.client.prefs.chat_toggles & CHAT_BANKCARD) && !force))
 					continue
 				if(!sound_atom)
-					sound_atom = A.drop_location() //in case we're inside a bodybag in a crate or something. doing this here to only process it if there's a valid mob who can hear the sound.
-				if(M.can_hear())
-					M.playsound_local(get_turf(sound_atom), 'sound/machines/twobeep_high.ogg', 50, TRUE)
-					to_chat(M, "[icon2html(icon_source, M)] [span_notice("[message]")]")
+					sound_atom = card.drop_location() //in case we're inside a bodybag in a crate or something. doing this here to only process it if there's a valid mob who can hear the sound.
+				if(potential_hearer.can_hear())
+					potential_hearer.playsound_local(get_turf(sound_atom), 'sound/machines/twobeep_high.ogg', 50, TRUE)
+					to_chat(potential_hearer, "[icon2html(icon_source, potential_hearer)] [span_notice("[message]")]")
 
 /**
  * Returns a string with the civilian bounty's description on it.