Initial pass of documentation on components (#46493)

code/datums/components/_component.dm

@@ -1,3 +1,13 @@
+/**
+  * # Component
+  *
+  * The component datum
+  *
+  * a component should be a single standalone unit
+  * of functionality, that works by receiving signals from it's parent
+  * object to provide some single functionality (i.e a slippery component)
+  * that makes the object it's attached to cause people to slip over
+  */
 /datum/component
 	var/dupe_mode = COMPONENT_DUPE_HIGHLANDER
 	var/dupe_type
@@ -6,7 +16,12 @@
 	//At a minimum RegisterWithParent and UnregisterFromParent should be used
 	//Make sure you also implement PostTransfer for any post transfer handling
 	var/can_transfer = FALSE
-
+/**
+  * Create a new component
+  *
+  * Arguments:
+  * * datum/P the parent datum this component reacts to signals from
+  */
 /datum/component/New(datum/P, ...)
 	parent = P
 	var/list/arguments = args.Copy(2)
@@ -52,6 +67,13 @@
 	RegisterWithParent()
 
 // If you want/expect to be moving the component around between parents, use this to register on the parent for signals
+/**
+  * Register the components signals with the parent object
+  *
+  * Use this proc to register signals with your parent object
+  * this is called when an object is created, or is transferred
+  * between objects
+  */
 /datum/component/proc/RegisterWithParent()
 	return
 
@@ -84,9 +106,29 @@
 
 	UnregisterFromParent()
 
+/**
+  * Unregister signals from our parent object
+  *
+  * Use this proc to unregister for signals from your parent object
+  * this is called when an object is destroyed, or is transferred
+  * between objects
+  * *
+  */
 /datum/component/proc/UnregisterFromParent()
 	return
 
+/**
+  * Register to listen for a signal from the passed in target
+  *
+  * This sets up a listening relationship such that when the target object emits a signal
+  * the source datum this proc is called upon, will recieve a callback to the given proctype
+  *
+  * Arguments:
+  * * datum/target The target to listen for signals from
+  * * sig_type_or_types Either a string signal name, or a list of signal names (strings)
+  * * proctype The proc to call back when the signal is emitted
+  * * override TODO, chase ninja to ask
+  */
 /datum/proc/RegisterSignal(datum/target, sig_type_or_types, proctype, override = FALSE)
 	if(QDELETED(src) || QDELETED(target))
 		return
@@ -118,7 +160,15 @@
 			lookup[sig_type][src] = TRUE
 
 	signal_enabled = TRUE
-
+/**
+  * Stop listening to a given signal from target
+  *
+  * Breaks the relationship between target and source datum, removing the callback when the signal fires
+  *
+  * Arguments:
+  * * datum/target Datum to stop listening to signals from
+  * * sig_typeor_types Signal string key or list of signal keys to stop listening to specifically
+  */
 /datum/proc/UnregisterSignal(datum/target, sig_type_or_types)
 	var/list/lookup = target.comp_lookup
 	if(!signal_procs || !signal_procs[target] || !lookup)
@@ -150,10 +200,20 @@
 
 /datum/component/proc/InheritComponent(datum/component/C, i_am_original)
 	return
-
+/**
+  * Callback Just before this component is transferred
+  *
+  * Use this to do any special cleanup you might need to do before being deregged from an object
+  *
+  */
 /datum/component/proc/PreTransfer()
 	return
-
+/**
+  * Callback Just after a component is transferred
+  *
+  * Use this to do any special setup you need to do after being moved to a new object
+  *
+  */
 /datum/component/proc/PostTransfer()
 	return COMPONENT_INCOMPATIBLE //Do not support transfer by default as you must properly support it
 
@@ -183,6 +243,12 @@
 		. |= CallAsync(C, proctype, arguments)
 
 // The type arg is casted so initial works, you shouldn't be passing a real instance into this
+/**
+  * Return any component assigned to this datum of the given type
+  *
+  * Arguments:
+  * * datum/component/c_type The typepath of the component you want to get a reference to
+  */
 /datum/proc/GetComponent(datum/component/c_type)
 	RETURN_TYPE(c_type)
 	if(initial(c_type.dupe_mode) == COMPONENT_DUPE_ALLOWED)
@@ -206,6 +272,12 @@
 			return C
 	return null
 
+/**
+  * Get all components of a given type that are attached to this datum
+  *
+  * Arguments:
+  * * c_type The component type path
+  */
 /datum/proc/GetComponents(c_type)
 	var/list/dc = datum_components
 	if(!dc)
@@ -266,11 +338,22 @@
 		return new_comp
 	return old_comp
 
+/**
+  * Get existing component of type, or create it and return a reference to it
+  *
+  * Use this if the item needs to exist at the time of this call, but may not have been created before now
+  *
+  * Arguments:
+  * * component_type The typepath of the component to create or return
+  * * ... additional arguments to be passed when creating the component if it does not exist
+  */
 /datum/proc/LoadComponent(component_type, ...)
 	. = GetComponent(component_type)
 	if(!.)
 		return AddComponent(arglist(args))
-
+/**
+  * Remove this component from it's parent
+  */
 /datum/component/proc/RemoveComponent()
 	if(!parent)
 		return
@@ -280,6 +363,14 @@
 	parent = null
 	SEND_SIGNAL(old_parent, COMSIG_COMPONENT_REMOVING, src)
 
+/**
+  * Transfer this component to another parent
+  *
+  * Component is taken from source datum
+  *
+  * Arguments:
+  * * datum/component/target Target datum to transfer to
+  */
 /datum/proc/TakeComponent(datum/component/target)
 	if(!target || target.parent == src)
 		return
@@ -295,7 +386,14 @@
 
 	if(target == AddComponent(target))
 		target._JoinParent()
-
+/**
+  * Transfer all components to target
+  *
+  * All components from source datum are taken
+  *
+  * Arguments:
+  * * /datum/target the target to move the components to
+  */
 /datum/proc/TransferComponents(datum/target)
 	var/list/dc = datum_components
 	if(!dc)
@@ -309,6 +407,6 @@
 		var/datum/component/C = comps
 		if(C.can_transfer)
 			target.TakeComponent(comps)
-
+///Return the object that is the host of any UI's that this component has
 /datum/component/ui_host()
 	return parent