Pointer explaining

Author: VMSolidus

code/datums/components/psionics/psi_sensitivity.dm

@@ -40,6 +40,11 @@
 
 /datum/component/psi_sensitivity/proc/modify_sensitivity(var/parent, var/effective_sensitivity)
 	SIGNAL_HANDLER
+	// Earlier, SendSignal() sent effective_sensitivity as a pointer by marking it as &effective_sensitivity.
+	// That means that for this proc, we have the memory address for the original var/effective_sensitivity located in /atom/movable/proc/check_psi_sensitivity()
+	// By marking it with the asterisk (*), I'm telling the game "Actually, add directly to the original variable from /atom/movable/proc/check_psi_sensitivity()"
+	// The reason we're doing this via pointer is that this allows any number of psi_sensitivity components to touch that variable.
+	// If we did this by a Return statement, only the first component would have been allowed to touch it, and all others get ignored.
 	*effective_sensitivity += sensitivity_modifier
 
 /**

code/modules/psionics/mob/mob_helpers.dm

@@ -41,7 +41,15 @@
  */
 /atom/movable/proc/check_psi_sensitivity()
 	var/effective_sensitivity = 0
+	// effective_sensitivity is being sent as a Pointer by marking it with the Ampersand (&)
+	// This means that components which have a RegisterSignal() associated with this will receive the memory address of the var/effective_sensitivity in this proc.
+	// They are then allowed to add or subtract to this proc's var directly, without needing to return a number.
+	// We have to do this with a pointer because it allows us to obtain a Sum of all psi-sensitivity modifiers.
+	// If we instead relied on a Return, we would only be able to get the modifier of the first component to respond.
 	SEND_SIGNAL(src, COMSIG_PSI_CHECK_SENSITIVITY, &effective_sensitivity)
+
+	// Pointers can be problematic if they're used to point to a value on a datum, since that can cause unintended hard deletes.
+	// Here however, their use is acceptable because the pointer will cease to exist as soon as the proc reaches this return statement.
 	return effective_sensitivity
 
 /mob/living/check_psi_sensitivity()