Porting datum components system updates.

code/datums/datum.dm

@@ -1,12 +1,42 @@
+/**
+  * The absolute base class for everything
+  *
+  * A datum instantiated has no physical world prescence, use an atom if you want something
+  * that actually lives in the world
+  *
+  * Be very mindful about adding variables to this class, they are inherited by every single
+  * thing in the entire game, and so you can easily cause memory usage to rise a lot with careless
+  * use of variables at this level
+  */
 /datum
+	/**
+	  * Tick count time when this object was destroyed.
+	  *
+	  * If this is non zero then the object has been garbage collected and is awaiting either
+	  * a hard del by the GC subsystme, or to be autocollected (if it has no references)
+	  */
 	var/gc_destroyed //Time when this object was destroyed.
-	var/list/active_timers  //for SStimer
-	var/list/datum_components //for /datum/components
+
+	/// Active timers with this datum as the target
+	var/list/active_timers
+	/// Status traits attached to this datum
 	var/list/status_traits
+	/// Components attached to this datum
+	/// Lazy associated list in the structure of `type:component/list of components`
+	var/list/datum_components
+	/// Any datum registered to receive signals from this datum is in this list
+	/// Lazy associated list in the structure of `signal:registree/list of registrees`
 	var/list/comp_lookup //it used to be for looking up components which had registered a signal but now anything can register
+	/// Lazy associated list in the structure of `signals:proctype` that are run when the datum receives that signal
 	var/list/list/datum/callback/signal_procs
+	/// Is this datum capable of sending signals?
+	/// Set to true when a signal has been registered
 	var/signal_enabled = FALSE
+
+	/// Datum level flags
 	var/datum_flags = NONE
+
+	/// A weak reference to another datum
 	var/datum/weakref/weak_reference
 
 #ifdef TESTING
@@ -18,9 +48,22 @@
 	var/list/cached_vars
 #endif
 
-// Default implementation of clean-up code.
-// This should be overridden to remove all references pointing to the object being destroyed.
-// Return the appropriate QDEL_HINT; in most cases this is QDEL_HINT_QUEUE.
+/**
+  * Default implementation of clean-up code.
+  *
+  * This should be overridden to remove all references pointing to the object being destroyed, if
+  * you do override it, make sure to call the parent and return it's return value by default
+  *
+  * Return an appropriate QDEL_HINT to modify handling of your deletion;
+  * in most cases this is QDEL_HINT_QUEUE.
+  *
+  * The base case is responsible for doing the following
+  * * Erasing timers pointing to this datum
+  * * Erasing compenents on this datum
+  * * Notifying datums listening to signals from this datum that we are going away
+  *
+  * Returns QDEL_HINT_QUEUE
+  */
 /datum/proc/Destroy(force=FALSE, ...)
 	tag = null
 	datum_flags &= ~DF_USE_TAG //In case something tries to REF us