Update SpacemanDMM linter defines to include documentation (#12067)

Port of tgstation/tgstation#71783

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

code/datums/brain_damage/severe.dm

@@ -216,8 +216,6 @@
 				else
 					to_chat(owner, "<span class='userdanger'>You feel your heart lurching in your chest...</span>")
 					owner.adjustOxyLoss(8)
-		else
-			SWITCH_EMPTY_STATEMENT
 
 /datum/brain_trauma/severe/discoordination
 	name = "Discoordination"

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(.)
 

code/modules/pool/components/swimming_felinid.dm

@@ -25,5 +25,3 @@
 			to_chat(parent, "<span class='userdanger'>You feel like you are never going to get out...</span>")
 		if(15 to 17)
 			L.emote("cry")
-		else
-			SWITCH_EMPTY_STATEMENT

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)

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("<span class='notice'>[src] yields [freebies > 1 ? "several free goodies" : "a free goody"]!</span>")