From f6053f55c95ea56ebea449ddd8a4e131da3013f7 Mon Sep 17 00:00:00 2001 From: Tad Hardesty Date: Sun, 29 Nov 2020 23:13:04 -0800 Subject: [PATCH] Add some method descriptions from neer's "Common Variables and Functions" --- code/__DEFINES/misc.dm | 9 +++++++-- code/__HELPERS/_lists.dm | 2 +- code/__HELPERS/mobs.dm | 5 ++++- code/game/objects/items.dm | 7 +++++-- 4 files changed, 17 insertions(+), 6 deletions(-) diff --git a/code/__DEFINES/misc.dm b/code/__DEFINES/misc.dm index f662aaa869b..95cb2657866 100644 --- a/code/__DEFINES/misc.dm +++ b/code/__DEFINES/misc.dm @@ -185,10 +185,15 @@ GLOBAL_LIST_EMPTY(bloody_footprints_cache) //subtypesof(), typesof() without the parent path #define subtypesof(typepath) ( typesof(typepath) - typepath ) -//Gets the turf this atom inhabits +/// Get the turf that `A` resides in, regardless of any containers. +/// +/// Use in favor of `A.loc` or `src.loc` so that things work correctly when +/// stored inside an inventory, locker, or other container. #define get_turf(A) (get_step(A, 0)) -//Same as above except gets the area instead +/// Get the ultimate area of `A`, similarly to [get_turf]. +/// +/// Use instead of `A.loc.loc`. #define get_area(A) (isarea(A) ? A : get_step(A, 0)?.loc) //Ghost orbit types: diff --git a/code/__HELPERS/_lists.dm b/code/__HELPERS/_lists.dm index c2e2660daff..08ca05396e8 100644 --- a/code/__HELPERS/_lists.dm +++ b/code/__HELPERS/_lists.dm @@ -229,7 +229,7 @@ return null -//Pick a random element from the list and remove it from the list. +/// Pick a random element from the list and remove it from the list. /proc/pick_n_take(list/L) RETURN_TYPE(L[_].type) if(L.len) diff --git a/code/__HELPERS/mobs.dm b/code/__HELPERS/mobs.dm index 76072973764..8eb31038267 100644 --- a/code/__HELPERS/mobs.dm +++ b/code/__HELPERS/mobs.dm @@ -250,7 +250,10 @@ GLOBAL_LIST_EMPTY(species_list) return ..() -///Timed action involving one mob user. Target is optional. +/// Timed action involving one mob user. Target is optional. +/// +/// Checks that `user` does not move, change hands, get stunned, etc. for the +/// given `delay`. Returns `TRUE` on success or `FALSE` on failure. /proc/do_after(mob/user, delay, atom/target, timed_action_flags = NONE, progress = TRUE, datum/callback/extra_checks) if(!user) return FALSE diff --git a/code/game/objects/items.dm b/code/game/objects/items.dm index dc2159958bf..c8573687674 100644 --- a/code/game/objects/items.dm +++ b/code/game/objects/items.dm @@ -454,6 +454,7 @@ GLOBAL_VAR_INIT(embedpocalypse, FALSE) // if true, all items will be able to emb /obj/item/proc/talk_into(mob/M, input, channel, spans, datum/language/language, list/message_mods) return ITALICS | REDUCE_RANGE +/// Called when a mob drops an item. /obj/item/proc/dropped(mob/user, silent = FALSE) SHOULD_CALL_PARENT(TRUE) for(var/X in actions) @@ -478,8 +479,10 @@ GLOBAL_VAR_INIT(embedpocalypse, FALSE) // if true, all items will be able to emb return /** - *called after an item is placed in an equipment slot - + * Called after an item is placed in an equipment slot. + * + * Note that hands count as slots. + * * Arguments: * * user is mob that equipped it * * slot uses the slot_X defines found in setup.dm for items that can be placed in multiple slots