Update documentation for body system code (#2556)

Content.Client/GameObjects/Components/Body/Scanner/BodyScannerDisplay.cs

@@ -174,9 +174,10 @@ namespace Content.Client.GameObjects.Components.Body.Scanner
                 return;
             }
 
+            // TODO BODY Mechanism description
             var message =
                 Loc.GetString(
-                    $"{mechanism.Name}\nHealth: {mechanism.CurrentDurability}/{mechanism.MaxDurability}\n{mechanism.Description}");
+                    $"{mechanism.Name}\nHealth: {mechanism.CurrentDurability}/{mechanism.MaxDurability}");
 
             MechanismInfoLabel.SetMessage(message);
         }

Content.Shared/GameObjects/Components/Body/Behavior/IMechanismBehavior.cs

@@ -6,10 +6,22 @@ using Robust.Shared.Interfaces.Serialization;
 
 namespace Content.Shared.GameObjects.Components.Body.Behavior
 {
+    /// <summary>
+    ///     Gives functionality to a <see cref="IMechanism"/> when added to it.
+    /// </summary>
     public interface IMechanismBehavior : IExposeData
     {
+        /// <summary>
+        ///     The body that owns the <see cref="IBodyPart"/> in which the
+        ///     <see cref="IMechanism"/> that owns this
+        ///     <see cref="IMechanismBehavior"/> is in.
+        /// </summary>
         IBody? Body { get; }
 
+        /// <summary>
+        ///     The part in which the <see cref="IMechanism"/> that owns this
+        ///     <see cref="IMechanismBehavior"/> is in.
+        /// </summary>
         IBodyPart? Part { get; }
 
         /// <summary>
@@ -21,14 +33,34 @@ namespace Content.Shared.GameObjects.Components.Body.Behavior
         /// <summary>
         ///     The entity that owns <see cref="Parent"/>.
         ///     For the entity owning the body that this mechanism may be in,
-        ///     see <see cref="IBody.Owner"/>
+        ///     see <see cref="Body"/>'s <see cref="IBody.Owner"/>.
         /// </summary>
         IEntity Owner { get; }
 
+        /// <summary>
+        ///     Called when this <see cref="IMechanismBehavior"/> is added to a
+        ///     <see cref="IMechanism"/>, during <see cref="IComponent.Initialize"/>.
+        ///     If it is added after component initialization,
+        ///     it is called immediately.
+        /// </summary>
+        /// <param name="parent">
+        ///     The mechanism that owns this <see cref="IMechanismBehavior"/>.
+        /// </param>
         void Initialize(IMechanism parent);
 
+        /// <summary>
+        ///     Called when this <see cref="IMechanismBehavior"/> is added to a
+        ///     <see cref="IMechanism"/>, during <see cref="IComponent.Startup"/>.
+        ///     If it is added after component startup, it is called immediately.
+        /// </summary>
         void Startup();
 
+        /// <summary>
+        ///     Runs an update cycle on this <see cref="IMechanismBehavior"/>.
+        /// </summary>
+        /// <param name="frameTime">
+        ///     The amount of seconds that passed since the last update.
+        /// </param>
         void Update(float frameTime);
 
         /// <summary>

Content.Shared/GameObjects/Components/Body/IBody.cs

@@ -4,6 +4,8 @@ using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using Content.Shared.GameObjects.Components.Body.Part;
 using Content.Shared.GameObjects.Components.Body.Part.Property;
+using Content.Shared.GameObjects.Components.Body.Preset;
+using Content.Shared.GameObjects.Components.Body.Template;
 using Robust.Shared.Interfaces.GameObjects;
 
 namespace Content.Shared.GameObjects.Components.Body
@@ -14,48 +16,80 @@ namespace Content.Shared.GameObjects.Components.Body
     /// </summary>
     public interface IBody : IComponent, IBodyPartContainer
     {
+        /// <summary>
+        ///     The name of the <see cref="BodyTemplatePrototype"/> used by this
+        ///     <see cref="IBody"/>.
+        /// </summary>
         public string? TemplateName { get; }
 
+        /// <summary>
+        ///     The name of the <see cref="BodyPresetPrototype"/> used by this
+        ///     <see cref="IBody"/>.
+        /// </summary>
         public string? PresetName { get; }
 
-        // TODO BODY tf is this
+        // TODO BODY Part slots
+        // TODO BODY Sensible templates
         /// <summary>
-        ///     Maps all parts on this template to its BodyPartType.
+        ///     Mapping of <see cref="IBodyPart"/> slots in this body to their
-        ///     For instance, "right arm" is mapped to "BodyPartType.arm" on the humanoid
+        ///     <see cref="BodyPartType"/>.
-        ///     template.
         /// </summary>
         public Dictionary<string, BodyPartType> Slots { get; }
 
         /// <summary>
-        ///     Maps slots to the part filling each one.
+        ///     Mapping of slots to the <see cref="IBodyPart"/> filling each one.
         /// </summary>
         public IReadOnlyDictionary<string, IBodyPart> Parts { get; }
 
-        // TODO BODY what am i doing
         /// <summary>
-        ///     Maps limb name to the list of their connections to other limbs.
+        ///     Mapping of slots to which other slots they connect to.
-        ///     For instance, on the humanoid template "torso" is mapped to a list
+        ///     For example, the torso could be mapped to a list containing
-        ///     containing "right arm", "left arm", "left leg", and "right leg".
+        ///     "right arm", "left arm", "left leg", and "right leg".
-        ///     This is mapped both ways during runtime, but in the prototype only one
+        ///     This is mapped both ways during runtime, but in the prototype
-        ///     way has to be defined, i.e., "torso" to "left arm" will automatically
+        ///     it only has to be defined one-way, "torso": "left arm" will automatically
-        ///     map "left arm" to "torso".
+        ///     map "left arm" to "torso" as well.
         /// </summary>
         public Dictionary<string, List<string>> Connections { get; }
 
         /// <summary>
-        ///     Maps a template slot to the ID of the <see cref="IBodyPart"/>
+        ///     Mapping of template slots to the ID of the <see cref="IBodyPart"/>
         ///     that should fill it. E.g. "right arm" : "BodyPart.arm.basic_human".
         /// </summary>
         public IReadOnlyDictionary<string, string> PartIds { get; }
 
         /// <summary>
-        ///     Adds the given <see cref="IBodyPart"/> into the given slot.
+        ///     Attempts to add a part to the given slot.
         /// </summary>
-        /// <returns>True if successful, false otherwise.</returns>
+        /// <param name="slot">The slot to add this part to.</param>
+        /// <param name="part">The part to add.</param>
+        /// <param name="force">
+        ///     Whether or not to check for the validity of the given <see cref="part"/>.
+        ///     Passing true does not guarantee it to be added, for example if it
+        ///     had already been added before.
+        /// </param>
+        /// <returns>
+        ///     true if the part was added, false otherwise even if it was already added.
+        /// </returns>
         bool TryAddPart(string slot, IBodyPart part, bool force = false);
 
+        /// <summary>
+        ///     Checks if there is a <see cref="IBodyPart"/> in the given slot.
+        /// </summary>
+        /// <param name="slot">The slot to look in.</param>
+        /// <returns>
+        ///     true if there is a part in the given <see cref="slot"/>,
+        ///     false otherwise.
+        /// </returns>
         bool HasPart(string slot);
 
+        /// <summary>
+        ///     Checks if this <see cref="IBody"/> contains the given <see cref="part"/>.
+        /// </summary>
+        /// <param name="part">The part to look for.</param>
+        /// <returns>
+        ///     true if the given <see cref="part"/> is attached to the body,
+        ///     false otherwise.
+        /// </returns>
         bool HasPart(IBodyPart part);
 
         /// <summary>
@@ -200,8 +234,18 @@ namespace Content.Shared.GameObjects.Components.Body
         List<(IBodyPart part, T property)> GetPartsWithProperty<T>() where T : class, IBodyPartProperty;
 
         // TODO BODY Make a slot object that makes sense to the human mind, and make it serializable. Imagine the possibilities!
+        /// <summary>
+        ///     Retrieves the slot at the given index.
+        /// </summary>
+        /// <param name="index">The index to look in.</param>
+        /// <returns>A pair of the slot name and part type occupying it.</returns>
         KeyValuePair<string, BodyPartType> SlotAt(int index);
 
+        /// <summary>
+        ///     Retrieves the part at the given index.
+        /// </summary>
+        /// <param name="index">The index to look in.</param>
+        /// <returns>A pair of the part name and body part occupying it.</returns>
         KeyValuePair<string, IBodyPart> PartAt(int index);
     }
 }

Content.Shared/GameObjects/Components/Body/Mechanism/IMechanism.cs

@@ -9,24 +9,23 @@ namespace Content.Shared.GameObjects.Components.Body.Mechanism
 {
     public interface IMechanism : IComponent
     {
+        /// <summary>
+        ///     The body that owns the <see cref="IBodyPart"/> in which this
+        ///     <see cref="IMechanism"/> is in.
+        /// </summary>
         IBody? Body { get; }
 
+        /// <summary>
+        ///     The part in which this <see cref="IMechanism"/> is in.
+        /// </summary>
         IBodyPart? Part { get; set; }
 
+        /// <summary>
+        ///     The behaviors attached to this <see cref="IMechanism"/>
+        ///     mapped by their type.
+        /// </summary>
         IReadOnlyDictionary<Type, IMechanismBehavior> Behaviors { get; }
 
-        /// <summary>
-        ///     Professional description of the <see cref="IMechanism"/>.
-        /// </summary>
-        string Description { get; set; }
-
-        /// <summary>
-        ///     The message to display upon examining a mob with this
-        ///     <see cref="IMechanism"/> added.
-        ///     If the string is empty (""), no message will be displayed.
-        /// </summary>
-        string ExamineMessage { get; set; }
-
         /// <summary>
         ///     Max HP of this <see cref="IMechanism"/>.
         /// </summary>
@@ -61,7 +60,8 @@ namespace Content.Shared.GameObjects.Components.Body.Mechanism
         BodyPartCompatibility Compatibility { get; set; }
 
         /// <summary>
-        ///    Adds a behavior if it does not exist already.
+        ///    Adds a <see cref="IMechanismBehavior"/> if this
+        ///     <see cref="IMechanism"/> does not have it already.
         /// </summary>
         /// <typeparam name="T">The behavior type to add.</typeparam>
         /// <returns>
@@ -69,10 +69,34 @@ namespace Content.Shared.GameObjects.Components.Body.Mechanism
         /// </returns>
         bool EnsureBehavior<T>(out T behavior) where T : IMechanismBehavior, new();
 
+        /// <summary>
+        ///     Checks if this <see cref="IMechanism"/> has the specified
+        ///     <see cref="IMechanismBehavior"/>.
+        /// </summary>
+        /// <typeparam name="T">
+        ///     The type of <see cref="IMechanismBehavior"/> to check for.
+        /// </typeparam>
+        /// <returns>
+        ///     true if it has the <see cref="IMechanismBehavior"/>, false otherwise.
+        /// </returns>
         bool HasBehavior<T>() where T : IMechanismBehavior;
 
+        /// <summary>
+        ///     Removes the specified <see cref="IMechanismBehavior"/> from this
+        ///     <see cref="IMechanism"/> if it has it.
+        /// </summary>
+        /// <typeparam name="T">
+        ///     The type of <see cref="IMechanismBehavior"/> to remove.
+        /// </typeparam>
+        /// <returns>true if it was removed, false otherwise.</returns>
         bool TryRemoveBehavior<T>() where T : IMechanismBehavior;
 
+        /// <summary>
+        ///     Runs an update cycle for this <see cref="IMechanism"/>.
+        /// </summary>
+        /// <param name="frameTime">
+        ///     The amount of seconds that passed since the last update.
+        /// </param>
         void Update(float frameTime);
 
         // TODO BODY Turn these into event listeners so they dont need to be exposed

Content.Shared/GameObjects/Components/Body/Mechanism/SharedMechanismComponent.cs

@@ -68,16 +68,13 @@ namespace Content.Shared.GameObjects.Components.Body.Mechanism
 
         public IReadOnlyDictionary<Type, IMechanismBehavior> Behaviors => _behaviors;
 
-        public string Description { get; set; } = string.Empty;
-
-        public string ExamineMessage { get; set; } = string.Empty;
-
         public int MaxDurability { get; set; }
 
         public int CurrentDurability { get; set; }
 
         public int DestroyThreshold { get; set; }
 
+        // TODO BODY: Surgery description and adding a message to the examine tooltip of the entity that owns this mechanism
         // TODO BODY
         public int Resistance { get; set; }
 
@@ -90,10 +87,6 @@ namespace Content.Shared.GameObjects.Components.Body.Mechanism
         {
             base.ExposeData(serializer);
 
-            serializer.DataField(this, m => m.Description, "description", string.Empty);
-
-            serializer.DataField(this, m => m.ExamineMessage, "examineMessage", string.Empty);
-
             serializer.DataField(this, m => m.MaxDurability, "maxDurability", 10);
 
             serializer.DataField(this, m => m.CurrentDurability, "currentDurability", MaxDurability);

Content.Shared/GameObjects/Components/Body/Networks/SharedBloodstreamComponent.cs

@@ -6,11 +6,11 @@ namespace Content.Shared.GameObjects.Components.Body.Networks
     public abstract class SharedBloodstreamComponent : Component
     {
         /// <summary>
-        ///     Attempt to transfer provided solution to internal solution.
+        ///     Attempts to transfer the provided solution to an internal solution.
-        ///     Only supports complete transfers
+        ///     Only supports complete transfers.
         /// </summary>
-        /// <param name="solution">Solution to be transferred</param>
+        /// <param name="solution">The solution to be transferred.</param>
-        /// <returns>Whether or not transfer was a success</returns>
+        /// <returns>Whether or not transfer was successful.</returns>
         public abstract bool TryTransferSolution(Solution solution);
     }
 }

Content.Shared/GameObjects/Components/Body/Part/BodyPartCompatibility.cs

@@ -4,7 +4,7 @@ using Robust.Shared.Serialization;
 namespace Content.Shared.GameObjects.Components.Body.Part
 {
     /// <summary>
-    ///     Used to determine whether a BodyPart can connect to another BodyPart.
+    ///     Determines whether two <see cref="IBodyPart"/>s can connect.
     /// </summary>
     [Serializable, NetSerializable]
     public enum BodyPartCompatibility

Content.Shared/GameObjects/Components/Body/Part/BodyPartExtensions.cs

@@ -7,16 +7,46 @@ namespace Content.Shared.GameObjects.Components.Body.Part
 {
     public static class BodyPartExtensions
     {
+        /// <summary>
+        ///     Checks if the given <see cref="IBodyPart"/> has the specified property.
+        /// </summary>
+        /// <param name="part">The <see cref="IBodyPart"/> to check in.</param>
+        /// <param name="type">
+        ///     The type of <see cref="IBodyPartProperty"/> to check for.
+        /// </param>
+        /// <returns>true if found, false otherwise.</returns>
         public static bool HasProperty(this IBodyPart part, Type type)
         {
             return part.Owner.HasComponent(type);
         }
 
+        /// <summary>
+        ///     Checks if the given <see cref="IBodyPart"/> has the specified property.
+        /// </summary>
+        /// <param name="part">The <see cref="IBodyPart"/> to check in.</param>
+        /// <typeparam name="T">
+        ///     The type of <see cref="IBodyPartProperty"/> to check for.
+        /// </typeparam>
+        /// <returns>true if found, false otherwise.</returns>
         public static bool HasProperty<T>(this IBodyPart part) where T : class, IBodyPartProperty
         {
             return part.HasProperty(typeof(T));
         }
 
+        /// <summary>
+        ///     Tries to retrieve the <see cref="IBodyPartProperty"/> with the
+        ///     specified type.
+        /// </summary>
+        /// <param name="part">The <see cref="IBodyPart"/> to search in.</param>
+        /// <param name="type">
+        ///     The type of <see cref="IBodyPartProperty"/> to search for.
+        /// </param>
+        /// <param name="property">
+        ///     The property, if it was found. Null otherwise.
+        /// </param>
+        /// <returns>
+        ///     true if a component with the specified type was found, false otherwise.
+        /// </returns>
         public static bool TryGetProperty(this IBodyPart part, Type type,
             [NotNullWhen(true)] out IBodyPartProperty? property)
         {
@@ -29,6 +59,20 @@ namespace Content.Shared.GameObjects.Components.Body.Part
             return (property = component as IBodyPartProperty) != null;
         }
 
+        /// <summary>
+        ///     Tries to retrieve the <see cref="IBodyPartProperty"/> with the
+        ///     specified type.
+        /// </summary>
+        /// <param name="part">The <see cref="IBodyPart"/> to search in.</param>
+        /// <typeparam name="T">
+        ///     The type of <see cref="IBodyPartProperty"/> to search for.
+        /// </typeparam>
+        /// <param name="property">
+        ///     The property, if it was found. Null otherwise.
+        /// </param>
+        /// <returns>
+        ///     true if a component with the specified type was found, false otherwise.
+        /// </returns>
         public static bool TryGetProperty<T>(this IBodyPart part, [NotNullWhen(true)] out T? property) where T : class, IBodyPartProperty
         {
             return part.Owner.TryGetComponent(out property);

Content.Shared/GameObjects/Components/Body/Part/BodyPartSymmetry.cs

@@ -3,6 +3,9 @@ using Robust.Shared.Serialization;
 
 namespace Content.Shared.GameObjects.Components.Body.Part
 {
+    /// <summary>
+    ///     Defines the symmetry of a <see cref="IBodyPart"/>.
+    /// </summary>
     [Serializable, NetSerializable]
     public enum BodyPartSymmetry
     {

Content.Shared/GameObjects/Components/Body/Part/BodyPartType.cs

@@ -4,8 +4,7 @@ using Robust.Shared.Serialization;
 namespace Content.Shared.GameObjects.Components.Body.Part
 {
     /// <summary>
-    ///     Each BodyPart has a BodyPartType used to determine a variety of things.
+    ///     Defines the type of a <see cref="IBodyPart"/>.
-    ///     For instance, what slots it can fit into.
     /// </summary>
     [Serializable, NetSerializable]
     public enum BodyPartType

Content.Shared/GameObjects/Components/Body/Part/IBodyPart.cs

@@ -9,6 +9,10 @@ namespace Content.Shared.GameObjects.Components.Body.Part
 {
     public interface IBodyPart : IComponent, IBodyPartContainer
     {
+        /// <summary>
+        ///     The <see cref="IBody"/> to which this <see cref="IBodyPart"/> is
+        ///     attached to.
+        /// </summary>
         IBody? Body { get; set; }
 
         /// <summary>
@@ -19,9 +23,8 @@ namespace Content.Shared.GameObjects.Components.Body.Part
         BodyPartType PartType { get; }
 
         /// <summary>
-        ///     Determines many things: how many mechanisms can be fit inside this
+        ///     Determines how many mechanisms can be fit inside this
-        ///     <see cref="IBodyPart"/>, whether a body can fit through tiny crevices,
+        ///     <see cref="IBodyPart"/>.
-        ///     etc.
         /// </summary>
         int Size { get; }
 
@@ -29,16 +32,20 @@ namespace Content.Shared.GameObjects.Components.Body.Part
         /// <summary>
         ///     Collection of all <see cref="IMechanism"/>s currently inside this
         ///     <see cref="IBodyPart"/>.
-        ///     To add and remove from this list see <see cref="AddMechanism"/> and
+        ///     To add and remove from this list see <see cref="TryAddMechanism"/> and
         ///     <see cref="RemoveMechanism"/>
         /// </summary>
         IReadOnlyCollection<IMechanism> Mechanisms { get; }
 
         /// <summary>
-        /// If body part is vital
+        ///     Whether or not the owning <see cref="Body"/> will die if all
+        ///     <see cref="IBodyPart"/>s of this type are removed from it.
         /// </summary>
         public bool IsVital { get; }
 
+        /// <summary>
+        ///     The symmetry of this <see cref="IBodyPart"/>.
+        /// </summary>
         public BodyPartSymmetry Symmetry { get; }
 
         /// <summary>
@@ -70,6 +77,16 @@ namespace Content.Shared.GameObjects.Components.Body.Part
         /// <returns>True if it can be added, false otherwise.</returns>
         bool CanAddMechanism(IMechanism mechanism);
 
+        /// <summary>
+        ///     Tries to add a <see cref="IMechanism"/> to this body.
+        /// </summary>
+        /// <param name="mechanism">The mechanism to add.</param>
+        /// <param name="force">
+        ///     Whether or not to check if the mechanism is compatible.
+        ///     Passing true does not guarantee it to be added, for example if
+        ///     it was already added before.
+        /// </param>
+        /// <returns>true if added, false otherwise even if it was already added.</returns>
         bool TryAddMechanism(IMechanism mechanism, bool force = false);
 
         /// <summary>

Content.Shared/GameObjects/Components/Body/Part/IBodyPartAdded.cs

@@ -1,4 +1,5 @@
 using System;
+using Robust.Shared.Interfaces.GameObjects;
 
 namespace Content.Shared.GameObjects.Components.Body.Part
 {
@@ -6,8 +7,13 @@ namespace Content.Shared.GameObjects.Components.Body.Part
     ///     This interface gives components behavior when a body part
     ///     is added to their owning entity.
     /// </summary>
-    public interface IBodyPartAdded
+    public interface IBodyPartAdded : IComponent
     {
+        /// <summary>
+        ///     Called when a <see cref="IBodyPart"/> is added to the
+        ///     entity owning this component.
+        /// </summary>
+        /// <param name="args">Information about the part that was added.</param>
         void BodyPartAdded(BodyPartAddedEventArgs args);
     }
 
@@ -19,8 +25,14 @@ namespace Content.Shared.GameObjects.Components.Body.Part
             Slot = slot;
         }
 
+        /// <summary>
+        ///     The part that was added.
+        /// </summary>
         public IBodyPart Part { get; }
 
+        /// <summary>
+        ///     The slot that <see cref="Part"/> was added to.
+        /// </summary>
         public string Slot { get; }
     }
 }

Content.Shared/GameObjects/Components/Body/Part/IBodyPartContainer.cs

@@ -1,14 +1,8 @@
 namespace Content.Shared.GameObjects.Components.Body.Part
 {
     /// <summary>
-    ///     Making a class inherit from this interface allows you to do many
+    ///     Defines a component as being capable of containing parts.
-    ///     things with it in the <see cref="SurgeryData"/> class.
+    ///     Used during surgery.
-    ///     This includes passing it as an argument to a
-    ///     <see cref="SurgeryData.SurgeryAction"/> delegate, as to later typecast
-    ///     it back to the original class type.
-    ///     Every BodyPart also needs an <see cref="IBodyPartContainer"/> to be
-    ///     its parent (i.e. the <see cref="IBody"/> holds many
-    ///     <see cref="IBodyPart"/>s, each of which have an upward reference to it).
     /// </summary>
     // TODO BODY Remove
     public interface IBodyPartContainer

Content.Shared/GameObjects/Components/Body/Part/IBodyPartRemoved.cs

@@ -8,6 +8,11 @@ namespace Content.Shared.GameObjects.Components.Body.Part
     /// </summary>
     public interface IBodyPartRemoved
     {
+        /// <summary>
+        ///     Called when a <see cref="IBodyPart"/> is removed from the
+        ///     entity owning this component.
+        /// </summary>
+        /// <param name="args">Information about the part that was removed.</param>
         void BodyPartRemoved(BodyPartRemovedEventArgs args);
     }
 
@@ -19,8 +24,14 @@ namespace Content.Shared.GameObjects.Components.Body.Part
             Slot = slot;
         }
 
+        /// <summary>
+        ///     The part that was removed.
+        /// </summary>
         public IBodyPart Part { get; }
 
+        /// <summary>
+        ///     The slot that <see cref="Part"/> was removed from.
+        /// </summary>
         public string Slot { get; }
     }
 }

Content.Shared/GameObjects/Components/Body/Part/Property/BodyPartPropertyComponent.cs

@@ -5,8 +5,9 @@ namespace Content.Shared.GameObjects.Components.Body.Part.Property
 {
     /// <summary>
     ///     Property attachable to a <see cref="IBodyPart"/>.
-    ///     For example, this is used to define the speed capabilities of a
+    ///     For example, this is used to define the speed capabilities of a leg.
-    ///     leg. The movement system will look for a LegProperty on all BodyParts.
+    ///     The movement system will look for a <see cref="LegComponent"/> on all
+    ///     <see cref="IBodyPart"/>.
     /// </summary>
     public abstract class BodyPartPropertyComponent : Component, IBodyPartProperty
     {

Content.Shared/GameObjects/Components/Body/Part/Property/ExtensionComponent.cs

@@ -3,13 +3,16 @@ using Robust.Shared.Serialization;
 
 namespace Content.Shared.GameObjects.Components.Body.Part.Property
 {
+    /// <summary>
+    ///     Defines the length of a <see cref="IBodyPart"/>.
+    /// </summary>
     [RegisterComponent]
     public class ExtensionComponent : BodyPartPropertyComponent
     {
         public override string Name => "Extension";
 
         /// <summary>
-        ///     Current distance (in tiles).
+        ///     Current distance in tiles.
         /// </summary>
         public float Distance { get; set; }
 

Content.Shared/GameObjects/Components/Body/Part/Property/GraspComponent.cs

@@ -3,7 +3,8 @@
 namespace Content.Shared.GameObjects.Components.Body.Part.Property
 {
     /// <summary>
-    ///     Defines an entity as being able to pick up items
+    ///     Defines a <see cref="IBodyPart"/> as being able to grasp around an entity,
+    ///     for example picking up an item.
     /// </summary>
     // TODO BODY Implement
     [RegisterComponent]

Content.Shared/GameObjects/Components/Body/Part/Property/IBodyPartProperty.cs

@@ -2,6 +2,9 @@
 
 namespace Content.Shared.GameObjects.Components.Body.Part.Property
 {
+    /// <summary>
+    ///     Defines a property for a <see cref="IBodyPart"/>.
+    /// </summary>
     public interface IBodyPartProperty : IComponent
     {
         bool Active { get; set; }

Content.Shared/GameObjects/Components/Body/Part/Property/LegComponent.cs

@@ -3,13 +3,16 @@ using Robust.Shared.Serialization;
 
 namespace Content.Shared.GameObjects.Components.Body.Part.Property
 {
+    /// <summary>
+    ///     Defines the speed at which a <see cref="IBodyPart"/> can move.
+    /// </summary>
     [RegisterComponent]
     public class LegComponent : BodyPartPropertyComponent
     {
         public override string Name => "Leg";
 
         /// <summary>
-        ///     Speed (in tiles per second).
+        ///     Speed in tiles per second.
         /// </summary>
         public float Speed { get; set; }
 

Content.Shared/GameObjects/Components/Body/Preset/BodyPresetPrototype.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using Content.Shared.GameObjects.Components.Body.Part;
 using Robust.Shared.Prototypes;
 using Robust.Shared.Serialization;
 using Robust.Shared.ViewVariables;
@@ -8,7 +9,7 @@ using YamlDotNet.RepresentationModel;
 namespace Content.Shared.GameObjects.Components.Body.Preset
 {
     /// <summary>
-    ///     Prototype for the BodyPreset class.
+    ///     Defines the <see cref="IBodyPart"/>s used in a <see cref="IBody"/>.
     /// </summary>
     [Prototype("bodyPreset")]
     [Serializable, NetSerializable]

Content.Shared/GameObjects/Components/Body/Surgery/BiologicalSurgeryDataComponent.cs

@@ -94,7 +94,7 @@ namespace Content.Shared.GameObjects.Components.Body.Surgery
             return null;
         }
 
-        public override string GetDescription(IEntity target)
+        public override string GetDescription()
         {
             if (Parent == null)
             {
@@ -107,21 +107,21 @@ namespace Content.Shared.GameObjects.Components.Body.Surgery
             {
                 // Case: skin is opened, but not clamped.
                 toReturn += Loc.GetString("The skin on {0:their} {1} has an incision, but it is prone to bleeding.\n",
-                    target, Parent.Name);
+                    Owner, Parent.Name);
             }
             else if (_skinOpened && _vesselsClamped && !_skinRetracted)
             {
                 // Case: skin is opened and clamped, but not retracted.
                 toReturn += Loc.GetString("The skin on {0:their} {1} has an incision, but it is not retracted.\n",
-                    target, Parent.Name);
+                    Owner, Parent.Name);
             }
             else if (_skinOpened && _vesselsClamped && _skinRetracted)
             {
                 // Case: skin is fully open.
-                toReturn += Loc.GetString("There is an incision on {0:their} {1}.\n", target, Parent.Name);
+                toReturn += Loc.GetString("There is an incision on {0:their} {1}.\n", Owner, Parent.Name);
                 foreach (var mechanism in _disconnectedOrgans)
                 {
-                    toReturn += Loc.GetString("{0:their} {1} is loose.\n", target, mechanism.Name);
+                    toReturn += Loc.GetString("{0:their} {1} is loose.\n", Owner, mechanism.Name);
                 }
             }
 

Content.Shared/GameObjects/Components/Body/Surgery/ISurgeon.cs

@@ -6,9 +6,8 @@ using Robust.Shared.Interfaces.GameObjects;
 namespace Content.Shared.GameObjects.Components.Body.Surgery
 {
     /// <summary>
-    ///     Interface representing an entity capable of performing surgery (performing operations on an
+    ///     Interface representing an entity capable of performing surgery,
-    ///     <see cref="SurgeryDataComponent"/> class).
+    ///     such as a circular saw.
-    ///     For an example see <see cref="SurgeryToolComponent"/>, which inherits from this class.
     /// </summary>
     public interface ISurgeon
     {
@@ -19,15 +18,16 @@ namespace Content.Shared.GameObjects.Components.Body.Surgery
             IEntity performer);
 
         /// <summary>
-        ///     How long it takes to perform a single surgery step (in seconds).
+        ///     How long it takes to perform a single surgery step in seconds.
         /// </summary>
         public float BaseOperationTime { get; set; }
 
         /// <summary>
-        ///     When performing a surgery, the <see cref="SurgeryDataComponent"/> may sometimes require selecting from a set of Mechanisms
+        ///     When performing a surgery, the <see cref="SurgeryDataComponent"/>
-        ///     to operate on.
+        ///     may sometimes require selecting from a set of
-        ///     This function is called in that scenario, and it is expected that you call the callback with one mechanism from the
+        ///     <see cref="IMechanism"/>s to operate on.
-        ///     provided list.
+        ///     This function is called in that scenario, and it is expected that you call
+        ///     the callback with one <see cref="IMechanism"/> from the provided list.
         /// </summary>
         public void RequestMechanism(IEnumerable<IMechanism> options, MechanismRequestCallback callback);
     }

Content.Shared/GameObjects/Components/Body/Surgery/SurgeryDataComponent.cs

@@ -3,14 +3,11 @@ using Content.Shared.GameObjects.Components.Body.Mechanism;
 using Content.Shared.GameObjects.Components.Body.Part;
 using Robust.Shared.GameObjects;
 using Robust.Shared.Interfaces.GameObjects;
-using Robust.Shared.Serialization;
 
 namespace Content.Shared.GameObjects.Components.Body.Surgery
 {
     /// <summary>
-    ///     This data class represents the state of a <see cref="IBodyPart"/> in
+    ///     Represents the current surgery state of a <see cref="IBodyPart"/>.
-    ///     regards to everything surgery related - whether there's an incision on
-    ///     it, whether the bone is broken, etc.
     /// </summary>
     public abstract class SurgeryDataComponent : Component
     {
@@ -29,10 +26,10 @@ namespace Content.Shared.GameObjects.Components.Body.Surgery
         protected BodyPartType? ParentType => Parent?.PartType;
 
         /// <summary>
-        ///     Returns the description of this current <see cref="IBodyPart"/> to
+        ///     Returns a description of this entity.
-        ///     be shown upon observing the given entity.
         /// </summary>
-        public abstract string GetDescription(IEntity target);
+        /// <returns>The description shown upon observing this entity.</returns>
+        public abstract string GetDescription();
 
         /// <summary>
         ///     Returns whether a <see cref="IMechanism"/> can be added into the

Content.Shared/GameObjects/Components/Body/Surgery/SurgeryType.cs

@@ -4,8 +4,9 @@ using Robust.Shared.Serialization;
 namespace Content.Shared.GameObjects.Components.Body.Surgery
 {
     /// <summary>
-    ///     Defines a surgery operation that can be performed.
+    ///     Types of surgery operations that can be performed.
     /// </summary>
+    // TODO BODY Move this to YAML?
     [Serializable, NetSerializable]
     public enum SurgeryType
     {

Content.Shared/GameObjects/Components/Body/Template/BodyTemplatePrototype.cs

@@ -10,7 +10,7 @@ using YamlDotNet.RepresentationModel;
 namespace Content.Shared.GameObjects.Components.Body.Template
 {
     /// <summary>
-    ///     Prototype for the BodyTemplate class.
+    ///     Defines the layout of a <see cref="IBody"/>.
     /// </summary>
     [Prototype("bodyTemplate")]
     [Serializable, NetSerializable]