Slight refactor and improvement of the hands inventory handling (#19282)

Slight refactor and improvement of the hands inventory handling procs,
DMDoc, SDMM markings.
Fixed a runtime with RIG cells removal.

code/modules/clothing/spacesuits/rig/rig_attackby.dm

@@ -167,10 +167,9 @@
 						to_chat(user, SPAN_NOTICE("You detach \the [cell] from \the [src]'s battery mount."))
 						for(var/obj/item/rig_module/module in installed_modules)
 							module.deactivate()
-						if(user.r_hand && user.l_hand)
-							cell.forceMove(get_turf(user))
-						else
-							cell.forceMove(user.put_in_hands(cell))
+
+						user.put_in_hands(cell)
+
 						cell = null
 					else
 						to_chat(user, SPAN_WARNING("There is nothing loaded in that mount."))

code/modules/mob/inventory.dm

@@ -178,33 +178,63 @@ var/list/slot_equipment_priority = list( \
 			return l_hand
 		return
 
-//Puts the item into our active hand if possible. returns 1 on success.
-/mob/proc/put_in_active_hand(var/obj/item/W)
-	return 0 // Moved to human procs because only they need to use hands.
+/**
+ * Puts the item in the active hand of the mob, if possible
+ *
+ * * item_to_equip - An `/obj/item` to try to equip in the hand
+ *
+ * Returns `TRUE` on success, `FALSE` otherwise
+ */
+/mob/proc/put_in_active_hand(obj/item/item_to_equip)
+	SHOULD_NOT_SLEEP(TRUE)
 
-//Puts the item into our inactive hand if possible. returns 1 on success.
-/mob/proc/put_in_inactive_hand(var/obj/item/W)
-	return 0 // As above.
+	return FALSE
+
+/**
+ * Puts the item in the active hand of the mob, if possible
+ *
+ * * item_to_equip - An `/obj/item` to try to equip in the hand
+ *
+ * Returns `TRUE` on success, `FALSE` otherwise
+ */
+/mob/proc/put_in_inactive_hand(obj/item/item_to_equip)
+	SHOULD_NOT_SLEEP(TRUE)
+
+	return FALSE
+
+/**
+ * Puts the item in an active hand if possible, failing that it tries an inactive hand
+ *
+ * If both fails, it drops the item on the floor and returns `FALSE`
+ *
+ * * item_to_equip - An `obj/item` to try to equip
+ * * check_adjacency - A boolean, if `TRUE` it checks if the mob is adjacent to the target
+ *
+ * Returns `TRUE` on successful equip on an hand, `FALSE` otherwise
+ */
+/mob/proc/put_in_hands(obj/item/item_to_equip, check_adjacency = FALSE)
+	SHOULD_NOT_SLEEP(TRUE)
+
+	if(QDELETED(item_to_equip))
+		return FALSE
+
+	if(!istype(item_to_equip))
+		return FALSE
 
-//Puts the item our active hand if possible. Failing that it tries our inactive hand. Returns 1 on success.
-//If both fail it drops it on the floor and returns 0.
-//This is probably the main one you need to know :)
-/mob/proc/put_in_hands(var/obj/item/W, var/check_adjacency = FALSE)
-	if(!W || !istype(W))
-		return 0
 	var/move_to_src = TRUE
 	if(check_adjacency)
 		move_to_src = FALSE
-		var/turf/origin = get_turf(W)
+		var/turf/origin = get_turf(item_to_equip)
 		if(Adjacent(origin))
 			move_to_src = TRUE
 	if(move_to_src)
-		W.forceMove(get_turf(src))
+		item_to_equip.forceMove(get_turf(src))
 	else
-		W.forceMove(get_turf(W))
-	W.reset_plane_and_layer()
-	W.dropped(src)
-	return 0
+		item_to_equip.forceMove(get_turf(item_to_equip))
+	item_to_equip.reset_plane_and_layer()
+	item_to_equip.dropped(src)
+
+	return FALSE
 
 // Removes an item from inventory and places it in the target atom.
 // If canremove or other conditions need to be checked then use unEquip instead.

code/modules/mob/living/carbon/alien/diona/diona_nymph.dm

@@ -153,9 +153,9 @@
 		to_chat(src, SPAN_WARNING("You are too small to pull that."))
 		return
 
-/mob/living/carbon/alien/diona/put_in_hands(var/obj/item/W) // No hands.
-	W.forceMove(get_turf(src))
-	return TRUE
+/mob/living/carbon/alien/diona/put_in_hands(obj/item/item_to_equip) // No hands.
+	item_to_equip.forceMove(get_turf(src))
+	return FALSE
 
 //Functions duplicated from humans, albeit slightly modified
 /mob/living/carbon/alien/diona/proc/set_species(var/new_species)

code/modules/mob/living/carbon/human/inventory.dm

@@ -462,20 +462,21 @@ This saves us from having to call add_fingerprint() any time something is put in
 	return items
 
 
-//Puts the item into our active hand if possible. returns 1 on success.
-/mob/living/carbon/human/put_in_active_hand(var/obj/item/W, set_disable_warning = FALSE)
-	return (hand ? equip_to_slot_if_possible(W, slot_l_hand, disable_warning = set_disable_warning) : equip_to_slot_if_possible(W, slot_r_hand, disable_warning = set_disable_warning))
+/mob/living/carbon/human/put_in_active_hand(obj/item/item_to_equip, set_disable_warning = FALSE)
+	var/hand_to_equip_to = hand ? slot_l_hand : slot_r_hand
+	return equip_to_slot_if_possible(item_to_equip, hand_to_equip_to, disable_warning = set_disable_warning)
 
-//Puts the item into our inactive hand if possible. returns 1 on success.
-/mob/living/carbon/human/put_in_inactive_hand(var/obj/item/W, set_disable_warning = FALSE)
-	return (hand ? equip_to_slot_if_possible(W, slot_r_hand, disable_warning = set_disable_warning) : equip_to_slot_if_possible(W, slot_l_hand, disable_warning = set_disable_warning))
+/mob/living/carbon/human/put_in_inactive_hand(obj/item/item_to_equip, set_disable_warning = FALSE)
+	var/hand_to_equip_to = hand ? slot_r_hand : slot_l_hand
+	return equip_to_slot_if_possible(item_to_equip, hand_to_equip_to, disable_warning = set_disable_warning)
 
-/mob/living/carbon/human/put_in_hands(var/obj/item/W)
-	if(!W)
+/mob/living/carbon/human/put_in_hands(obj/item/item_to_equip)
+	if(QDELETED(item_to_equip) || !istype(item_to_equip))
 		return FALSE
-	if(put_in_active_hand(W, TRUE))
+
+	if(put_in_active_hand(item_to_equip, TRUE))
 		return TRUE
-	else if(put_in_inactive_hand(W, TRUE))
+	else if(put_in_inactive_hand(item_to_equip, TRUE))
 		return TRUE
 	else
 		return ..()

code/modules/mob/living/silicon/robot/inventory.dm

@@ -230,25 +230,28 @@
 	else
 		to_chat(src, SPAN_NOTICE("You need to disable a module first!"))
 
-/mob/living/silicon/robot/put_in_hands(var/obj/item/W) // Maybe hands.
+/mob/living/silicon/robot/put_in_hands(obj/item/item_to_equip) // Maybe hands.
+	if(QDELETED(item_to_equip) || !istype(item_to_equip))
+		return FALSE
+
 	var/obj/item/gripper/G = get_active_hand()
 	if (istype(G))
-		if(!G.wrapped && G.grip_item(W, src, TRUE))
+		if(!G.wrapped && G.grip_item(item_to_equip, src, TRUE))
 			return TRUE
 	if (istype(module_state_1, /obj/item/gripper))
 		G = module_state_1
-		if (!G.wrapped && G.grip_item(W, src, TRUE))
+		if (!G.wrapped && G.grip_item(item_to_equip, src, TRUE))
 			return TRUE
 	else if (istype(module_state_2, /obj/item/gripper))
 		G = module_state_2
-		if (!G.wrapped && G.grip_item(W, src, TRUE))
+		if (!G.wrapped && G.grip_item(item_to_equip, src, TRUE))
 			return TRUE
 	else if (istype(module_state_3, /obj/item/gripper))
 		G = module_state_3
-		if (!G.wrapped && G.grip_item(W, src, TRUE))
+		if (!G.wrapped && G.grip_item(item_to_equip, src, TRUE))
 			return TRUE
 
-	W.forceMove(get_turf(src))
+	item_to_equip.forceMove(get_turf(src))
 	return FALSE
 
 /mob/living/silicon/robot/remove_from_mob(var/obj/O) //Necessary to clear gripper when trying to place items in things (grinders, smartfridges, vendors, etc)

code/modules/mob/living/silicon/silicon_procs.dm

@@ -9,5 +9,5 @@
 	accent = chosen_accent
 	to_chat(src, SPAN_NOTICE("You have set your synthesizer to mimic the [chosen_accent] accent."))
 
-/mob/living/silicon/put_in_hands(obj/item/W)
-	..(W, TRUE)
+/mob/living/silicon/put_in_hands(obj/item/item_to_equip)
+	. = ..(item_to_equip, TRUE)

code/modules/mob/living/simple_animal/simple_animal.dm

@@ -823,9 +823,12 @@
 /mob/living/simple_animal/get_speech_ending(verb, var/ending)
 	return verb
 
-/mob/living/simple_animal/put_in_hands(var/obj/item/W) // No hands.
-	W.forceMove(get_turf(src))
-	return 1
+/mob/living/simple_animal/put_in_hands(obj/item/item_to_equip)
+	if(QDELETED(item_to_equip) || !istype(item_to_equip))
+		return FALSE
+
+	item_to_equip.forceMove(get_turf(src))
+	return FALSE
 
 // Harvest an animal's delicious byproducts
 /mob/living/simple_animal/proc/harvest(var/mob/user)