From e17b522c5e0861c5f56aa25af2cdd0a633b264ce Mon Sep 17 00:00:00 2001 From: Lucy Date: Wed, 25 Dec 2024 03:50:38 -0500 Subject: [PATCH] Update SpacemanDMM linter defines to include documentation (#12067) Port of https://github.com/tgstation/tgstation/pull/71783 --- code/__DEFINES/spaceman_dmm.dm | 50 +++++++++++++++++-- code/datums/brain_damage/severe.dm | 2 - code/modules/mob/mob_helpers.dm | 6 --- .../pool/components/swimming_felinid.dm | 2 - code/modules/surgery/advanced/lobotomy.dm | 2 - code/modules/vending/_vending.dm | 2 - 6 files changed, 47 insertions(+), 17 deletions(-) diff --git a/code/__DEFINES/spaceman_dmm.dm b/code/__DEFINES/spaceman_dmm.dm index 818908fdc8aae..d7f66474c322f 100644 --- a/code/__DEFINES/spaceman_dmm.dm +++ b/code/__DEFINES/spaceman_dmm.dm @@ -1,29 +1,73 @@ -#define SWITCH_EMPTY_STATEMENT ; //For the new switch rand check so we can have an empty condition remove when no longer needed // Interfaces for the SpacemanDMM linter, define'd to nothing when the linter // is not in use. // The SPACEMAN_DMM define is set by the linter and other tooling when it runs. #ifdef SPACEMAN_DMM + /** + * Sets a return type expression for a proc. The return type can take the forms: + + * `/typepath` - a raw typepath. The return type of the proc is the type named. + + * `param` - a typepath given as a parameter, for procs which return an instance of the passed-in type. + + * `param.type` - the static type of a passed-in parameter, for procs which + * return their input or otherwise another value of the same type. + + * `param[_].type` - the static type of a passed-in parameter, with one level + * of `/list` stripped, for procs which select one item from a list. The `[_]` + * may be repeated to strip more levels of `/list`. + */ #define RETURN_TYPE(X) set SpacemanDMM_return_type = X + /** + * If set, will enable a diagnostic on children of the proc it is set on which do + * not contain any `..()` parent calls. This can help with finding situations + * where a signal or other important handling in the parent proc is being skipped. + * Child procs may set this setting to `0` instead to override the check. + */ #define SHOULD_CALL_PARENT(X) set SpacemanDMM_should_call_parent = X - #define UNLINT(X) SpacemanDMM_unlint(X) + /** + * If set, raise a warning for any child procs that override this one, + * regardless of if it calls parent or not. + * This functions in a similar way to the `final` keyword in some languages. + * This cannot be disabled by child overrides. + */ #define SHOULD_NOT_OVERRIDE(X) set SpacemanDMM_should_not_override = X + /** + * If set, raise a warning if the proc or one of the sub-procs it calls + * uses a blocking call, such as `sleep()` or `input()` without using `set waitfor = 0` + * This cannot be disabled by child overrides. + */ #define SHOULD_NOT_SLEEP(X) set SpacemanDMM_should_not_sleep = X + /** + * If set, ensure a proc is 'pure', such that it does not make any changes + * outside itself or output. This also checks to make sure anything using + * this proc doesn't invoke it without making use of the return value. + * This cannot be disabled by child overrides. + */ #define SHOULD_BE_PURE(X) set SpacemanDMM_should_be_pure = X + ///Private procs can only be called by things of exactly the same type. #define PRIVATE_PROC(X) set SpacemanDMM_private_proc = X + ///Protected procs can only be call by things of the same type *or subtypes*. #define PROTECTED_PROC(X) set SpacemanDMM_protected_proc = X + ///If set, will not lint. + #define UNLINT(X) SpacemanDMM_unlint(X) + + ///If set, overriding their value isn't permitted by types that inherit it. #define VAR_FINAL var/SpacemanDMM_final + ///Private vars can only be called by things of exactly the same type. #define VAR_PRIVATE var/SpacemanDMM_private + ///Protected vars can only be called by things of the same type *or subtypes*. #define VAR_PROTECTED var/SpacemanDMM_protected #else #define RETURN_TYPE(X) #define SHOULD_CALL_PARENT(X) - #define UNLINT(X) X #define SHOULD_NOT_OVERRIDE(X) #define SHOULD_NOT_SLEEP(X) #define SHOULD_BE_PURE(X) #define PRIVATE_PROC(X) #define PROTECTED_PROC(X) + #define UNLINT(X) X + #define VAR_FINAL var #define VAR_PRIVATE var #define VAR_PROTECTED var diff --git a/code/datums/brain_damage/severe.dm b/code/datums/brain_damage/severe.dm index c670462932fc8..0693c29982bf3 100644 --- a/code/datums/brain_damage/severe.dm +++ b/code/datums/brain_damage/severe.dm @@ -216,8 +216,6 @@ else to_chat(owner, "You feel your heart lurching in your chest...") owner.adjustOxyLoss(8) - else - SWITCH_EMPTY_STATEMENT /datum/brain_trauma/severe/discoordination name = "Discoordination" diff --git a/code/modules/mob/mob_helpers.dm b/code/modules/mob/mob_helpers.dm index 541694823735c..b6817f6f7404b 100644 --- a/code/modules/mob/mob_helpers.dm +++ b/code/modules/mob/mob_helpers.dm @@ -106,8 +106,6 @@ newletter += "[newletter]" if(20) newletter += "[newletter][newletter]" - else - SWITCH_EMPTY_STATEMENT . += "[newletter]" return sanitize(.) @@ -151,8 +149,6 @@ newletter = "nglu" if(5) newletter = "glor" - else - SWITCH_EMPTY_STATEMENT . += newletter return sanitize(.) @@ -195,8 +191,6 @@ newletter = "kth" if(5) newletter = "toc" - else - SWITCH_EMPTY_STATEMENT . += newletter return sanitize(.) diff --git a/code/modules/pool/components/swimming_felinid.dm b/code/modules/pool/components/swimming_felinid.dm index b5f9b069b98d4..6cd36aa17a981 100644 --- a/code/modules/pool/components/swimming_felinid.dm +++ b/code/modules/pool/components/swimming_felinid.dm @@ -25,5 +25,3 @@ to_chat(parent, "You feel like you are never going to get out...") if(15 to 17) L.emote("cry") - else - SWITCH_EMPTY_STATEMENT diff --git a/code/modules/surgery/advanced/lobotomy.dm b/code/modules/surgery/advanced/lobotomy.dm index cb041d55f3413..39ca16cf85abe 100644 --- a/code/modules/surgery/advanced/lobotomy.dm +++ b/code/modules/surgery/advanced/lobotomy.dm @@ -57,8 +57,6 @@ target.gain_trauma_type(BRAIN_TRAUMA_SEVERE, TRAUMA_RESILIENCE_MAGIC) if(3) target.gain_trauma_type(BRAIN_TRAUMA_SPECIAL, TRAUMA_RESILIENCE_MAGIC) - else - SWITCH_EMPTY_STATEMENT return TRUE /datum/surgery_step/lobotomize/failure(mob/user, mob/living/carbon/target, obj/item/tool, datum/surgery/surgery) diff --git a/code/modules/vending/_vending.dm b/code/modules/vending/_vending.dm index d8c49e9a55811..679335aa23952 100644 --- a/code/modules/vending/_vending.dm +++ b/code/modules/vending/_vending.dm @@ -584,8 +584,6 @@ tilt(user) if(91 to 100) tilt(user, crit=TRUE) - else - SWITCH_EMPTY_STATEMENT /obj/machinery/vending/proc/freebie(mob/fatty, freebies) visible_message("[src] yields [freebies > 1 ? "several free goodies" : "a free goody"]!")