diff --git a/code/_onclick/click.dm b/code/_onclick/click.dm index 5fe96c168ac..bcfed9aa069 100644 --- a/code/_onclick/click.dm +++ b/code/_onclick/click.dm @@ -29,15 +29,15 @@ adj += S.nextmove_adjust() next_move = world.time + ((num + adj)*mod) -/* - Before anything else, defer these calls to a per-mobtype handler. This allows us to - remove istype() spaghetti code, but requires the addition of other handler procs to simplify it. - - Alternately, you could hardcode every mob's variation in a flat ClickOn() proc; however, - that's a lot of code duplication and is hard to maintain. - - Note that this proc can be overridden, and is in the case of screen objects. -*/ +/** + * Before anything else, defer these calls to a per-mobtype handler. This allows us to + * remove istype() spaghetti code, but requires the addition of other handler procs to simplify it. + * + * Alternately, you could hardcode every mob's variation in a flat [/mob/proc/ClickOn] proc; however, + * that's a lot of code duplication and is hard to maintain. + * + * Note that this proc can be overridden, and is in the case of screen objects. + */ /atom/Click(location,control,params) if(flags_1 & INITIALIZED_1) SEND_SIGNAL(src, COMSIG_CLICK, location, control, params, usr) @@ -51,19 +51,19 @@ if(flags_1 & INITIALIZED_1) usr.MouseWheelOn(src, delta_x, delta_y, params) -/* - Standard mob ClickOn() - Handles exceptions: Buildmode, middle click, modified clicks, mech actions - - After that, mostly just check your state, check whether you're holding an item, - check whether you're adjacent to the target, then pass off the click to whoever - is receiving it. - The most common are: - * mob/UnarmedAttack(atom,adjacent) - used here only when adjacent, with no item in hand; in the case of humans, checks gloves - * atom/attackby(item,user) - used only when adjacent - * item/afterattack(atom,user,adjacent,params) - used both ranged and adjacent - * mob/RangedAttack(atom,params) - used only ranged, only used for tk and laser eyes but could be changed -*/ +/** + * Standard mob ClickOn() + * Handles exceptions: Buildmode, middle click, modified clicks, mech actions + * + * After that, mostly just check your state, check whether you're holding an item, + * check whether you're adjacent to the target, then pass off the click to whoever + * is receiving it. + * The most common are: + * * [mob/proc/UnarmedAttack] (atom,adjacent) - used here only when adjacent, with no item in hand; in the case of humans, checks gloves + * * [atom/proc/attackby] (item,user) - used only when adjacent + * * [obj/item/proc/afterattack] (atom,user,adjacent,params) - used both ranged and adjacent + * * [mob/proc/RangedAttack] (atom,params) - used only ranged, only used for tk and laser eyes but could be changed + */ /mob/proc/ClickOn( atom/A, params ) if(world.time <= next_click) return @@ -158,7 +158,7 @@ else RangedAttack(A,params) -//Is the atom obscured by a PREVENT_CLICK_UNDER_1 object above it +/// Is the atom obscured by a PREVENT_CLICK_UNDER_1 object above it /atom/proc/IsObscured() if(!isturf(loc)) //This only makes sense for things directly on turfs for now return FALSE @@ -177,9 +177,11 @@ return TRUE return FALSE +/** + * A backwards depth-limited breadth-first-search to see if the target is + * logically "in" anything adjacent to us. + */ /atom/movable/proc/CanReach(atom/ultimate_target, obj/item/tool, view_only = FALSE) - // A backwards depth-limited breadth-first-search to see if the target is - // logically "in" anything adjacent to us. var/list/direct_access = DirectAccess() var/depth = 1 + (view_only ? STORAGE_VIEW_DEPTH : INVENTORY_DEPTH) @@ -243,48 +245,48 @@ return qdel(dummy) -// Default behavior: ignore double clicks (the second click that makes the doubleclick call already calls for a normal click) +/// Default behavior: ignore double clicks (the second click that makes the doubleclick call already calls for a normal click) /mob/proc/DblClickOn(atom/A, params) return -/* - Translates into attack_hand, etc. - - Note: proximity_flag here is used to distinguish between normal usage (flag=1), - and usage when clicking on things telekinetically (flag=0). This proc will - not be called at ranged except with telekinesis. - - proximity_flag is not currently passed to attack_hand, and is instead used - in human click code to allow glove touches only at melee range. -*/ +/** + * Translates into [atom/proc/attack_hand], etc. + * + * Note: proximity_flag here is used to distinguish between normal usage (flag=1), + * and usage when clicking on things telekinetically (flag=0). This proc will + * not be called at ranged except with telekinesis. + * + * proximity_flag is not currently passed to attack_hand, and is instead used + * in human click code to allow glove touches only at melee range. + */ /mob/proc/UnarmedAttack(atom/A, proximity_flag) if(ismob(A)) changeNext_move(CLICK_CD_MELEE) return -/* - Ranged unarmed attack: - - This currently is just a default for all mobs, involving - laser eyes and telekinesis. You could easily add exceptions - for things like ranged glove touches, spitting alien acid/neurotoxin, - animals lunging, etc. -*/ +/** + * Ranged unarmed attack: + * + * This currently is just a default for all mobs, involving + * laser eyes and telekinesis. You could easily add exceptions + * for things like ranged glove touches, spitting alien acid/neurotoxin, + * animals lunging, etc. + */ /mob/proc/RangedAttack(atom/A, params) SEND_SIGNAL(src, COMSIG_MOB_ATTACK_RANGED, A, params) -/* - Restrained ClickOn - - Used when you are handcuffed and click things. - Not currently used by anything but could easily be. -*/ +/** + * Restrained ClickOn + * + * Used when you are handcuffed and click things. + * Not currently used by anything but could easily be. + */ /mob/proc/RestrainedClickOn(atom/A) return /** - *Middle click - *Mainly used for swapping hands + * Middle click + * Mainly used for swapping hands */ /mob/proc/MiddleClickOn(atom/A) . = SEND_SIGNAL(src, COMSIG_MOB_MIDDLECLICKON, A) @@ -292,11 +294,11 @@ return swap_hand() -/* - Shift click - For most mobs, examine. - This is overridden in ai.dm -*/ +/** + * Shift click + * For most mobs, examine. + * This is overridden in ai.dm + */ /mob/proc/ShiftClickOn(atom/A) A.ShiftClick(src) return @@ -307,11 +309,10 @@ user.examinate(src) return -/* - Ctrl click - For most objects, pull -*/ - +/** + * Ctrl click + * For most objects, pull + */ /mob/proc/CtrlClickOn(atom/A) A.CtrlClick(src) return @@ -331,10 +332,10 @@ H.changeNext_move(CLICK_CD_MELEE) else ..() -/* - Alt click - Unused except for AI -*/ +/** + * Alt click + * Unused except for AI + */ /mob/proc/AltClickOn(atom/A) . = SEND_SIGNAL(src, COMSIG_MOB_ALTCLICKON, A) if(. & COMSIG_MOB_CANCEL_CLICKON) @@ -348,7 +349,7 @@ user.listed_turf = T user.client.statpanel = T.name -// Use this instead of /mob/proc/AltClickOn(atom/A) where you only want turf content listing without additional atom alt-click interaction +/// Use this instead of [/mob/proc/AltClickOn] where you only want turf content listing without additional atom alt-click interaction /atom/proc/AltClickNoInteract(mob/user, atom/A) var/turf/T = get_turf(A) if(T && user.TurfAdjacent(T)) @@ -358,10 +359,10 @@ /mob/proc/TurfAdjacent(turf/T) return T.Adjacent(src) -/* - Control+Shift click - Unused except for AI -*/ +/** + * Control+Shift click + * Unused except for AI + */ /mob/proc/CtrlShiftClickOn(atom/A) A.CtrlShiftClick(src) return @@ -379,7 +380,7 @@ face_atom: turns the mob towards what you clicked on */ -// Simple helper to face what you clicked on, in case it should be needed in more than one place +/// Simple helper to face what you clicked on, in case it should be needed in more than one place /mob/proc/face_atom(atom/A) if( buckled || stat != CONSCIOUS || !A || !x || !y || !A.x || !A.y ) return @@ -452,8 +453,7 @@ T.Click(location, control, params) . = 1 -/* MouseWheelOn */ - +/// MouseWheelOn /mob/proc/MouseWheelOn(atom/A, delta_x, delta_y, params) return diff --git a/code/_onclick/item_attack.dm b/code/_onclick/item_attack.dm index 4dc2da3f741..3028bf7a904 100644 --- a/code/_onclick/item_attack.dm +++ b/code/_onclick/item_attack.dm @@ -1,11 +1,11 @@ /** - *This is the proc that handles the order of an item_attack. - *The order of procs called is: - *tool_act on the target. If it returns TRUE, the chain will be stopped. - *pre_attack() on src. If this returns TRUE, the chain will be stopped. - *attackby on the target. If it returns TRUE, the chain will be stopped. - *and lastly - *afterattack. The return value does not matter. + * This is the proc that handles the order of an item_attack. + * + * The order of procs called is: + * * [/atom/proc/tool_act] on the target. If it returns TRUE, the chain will be stopped. + * * [/obj/item/proc/pre_attack] on src. If this returns TRUE, the chain will be stopped. + * * [/atom/proc/attackby] on the target. If it returns TRUE, the chain will be stopped. + * * [/obj/item/proc/afterattack]. The return value does not matter. */ /obj/item/proc/melee_attack_chain(mob/user, atom/target, params) if(tool_behaviour && target.tool_act(user, src, tool_behaviour)) @@ -19,18 +19,37 @@ return afterattack(target, user, TRUE, params) -// Called when the item is in the active hand, and clicked; alternately, there is an 'activate held object' verb or you can hit pagedown. +/// Called when the item is in the active hand, and clicked; alternately, there is an 'activate held object' verb or you can hit pagedown. /obj/item/proc/attack_self(mob/user) if(SEND_SIGNAL(src, COMSIG_ITEM_ATTACK_SELF, user) & COMPONENT_NO_INTERACT) return interact(user) +/** + * Called on the item before it hits something + * + * Arguments: + * * atom/A - The atom about to be hit + * * mob/living/user - The mob doing the htting + * * params - click params such as alt/shift etc + * + * See: [/obj/item/proc/melee_attack_chain] + */ /obj/item/proc/pre_attack(atom/A, mob/living/user, params) //do stuff before attackby! if(SEND_SIGNAL(src, COMSIG_ITEM_PRE_ATTACK, A, user, params) & COMPONENT_NO_ATTACK) return TRUE return FALSE //return TRUE to avoid calling attackby after this proc does stuff -// No comment +/** + * Called on an object being hit by an item + * + * Arguments: + * * obj/item/W - The item hitting this atom + * * mob/user - The wielder of this item + * * params - click params such as alt/shift etc + * + * See: [/obj/item/proc/melee_attack_chain] + */ /atom/proc/attackby(obj/item/W, mob/user, params) if(SEND_SIGNAL(src, COMSIG_PARENT_ATTACKBY, W, user, params) & COMPONENT_NO_AFTERATTACK) return TRUE @@ -45,7 +64,13 @@ user.changeNext_move(CLICK_CD_MELEE) return I.attack(src, user) - +/** + * Called from [/mob/living/attackby] + * + * Arguments: + * * mob/living/M - The mob being hit by this item + * * mob/living/user - The mob hitting with this item + */ /obj/item/proc/attack(mob/living/M, mob/living/user) if(SEND_SIGNAL(src, COMSIG_ITEM_ATTACK, M, user) & COMPONENT_ITEM_NO_ATTACK) return @@ -75,7 +100,7 @@ add_fingerprint(user) -//the equivalent of the standard version of attack() but for object targets. +/// The equivalent of the standard version of [/obj/item/proc/attack] but for object targets. /obj/item/proc/attack_obj(obj/O, mob/living/user) if(SEND_SIGNAL(src, COMSIG_ITEM_ATTACK_OBJ, O, user) & COMPONENT_NO_ATTACK_OBJ) return @@ -85,6 +110,7 @@ user.do_attack_animation(O) O.attacked_by(src, user) +/// Called from [/obj/item/proc/attack_obj] and [/obj/item/proc/attack] if the attack succeeds /atom/movable/proc/attacked_by() return @@ -115,13 +141,20 @@ else return ..() -// Proximity_flag is 1 if this afterattack was called on something adjacent, in your square, or on your person. -// Click parameters is the params string from byond Click() code, see that documentation. +/** + * Last proc in the [/obj/item/proc/melee_attack_chain] + * + * Arguments: + * * atom/target - The thing that was hit + * * mob/user - The mob doing the hitting + * * proximity_flag - is 1 if this afterattack was called on something adjacent, in your square, or on your person. + * * click_parameters - is the params string from byond [/atom/proc/Click] code, see that documentation. + */ /obj/item/proc/afterattack(atom/target, mob/user, proximity_flag, click_parameters) SEND_SIGNAL(src, COMSIG_ITEM_AFTERATTACK, target, user, proximity_flag, click_parameters) SEND_SIGNAL(user, COMSIG_MOB_ITEM_AFTERATTACK, target, user, proximity_flag, click_parameters) -// Called if the target gets deleted by our attack +/// Called if the target gets deleted by our attack /obj/item/proc/attack_qdeleted(atom/target, mob/user, proximity_flag, click_parameters) SEND_SIGNAL(src, COMSIG_ITEM_ATTACK_QDELETED, target, user, proximity_flag, click_parameters) SEND_SIGNAL(user, COMSIG_MOB_ITEM_ATTACK_QDELETED, target, user, proximity_flag, click_parameters) diff --git a/code/_onclick/other_mobs.dm b/code/_onclick/other_mobs.dm index 1d6c4d82852..00ab119f219 100644 --- a/code/_onclick/other_mobs.dm +++ b/code/_onclick/other_mobs.dm @@ -22,7 +22,7 @@ SEND_SIGNAL(src, COMSIG_HUMAN_MELEE_UNARMED_ATTACK, A, proximity) A.attack_hand(src) -//Return TRUE to cancel other attack hand effects that respect it. +/// Return TRUE to cancel other attack hand effects that respect it. /atom/proc/attack_hand(mob/user) . = FALSE if(!(interaction_flags_atom & INTERACT_ATOM_NO_FINGERPRINT_ATTACK_HAND))