Docs/cleanup for node system.

Content.Server/NodeContainer/EntitySystems/NodeContainerSystem.cs

@@ -4,6 +4,10 @@ using Robust.Shared.GameObjects;
 
 namespace Content.Server.NodeContainer.EntitySystems
 {
+    /// <summary>
+    ///     Manages <see cref="NodeContainerComponent"/> events.
+    /// </summary>
+    /// <seealso cref="NodeGroupSystem"/>
     [UsedImplicitly]
     public class NodeContainerSystem : EntitySystem
     {

Content.Server/NodeContainer/EntitySystems/NodeGroupSystem.cs

@@ -17,11 +17,13 @@ using Robust.Shared.Utility;
 
 namespace Content.Server.NodeContainer.EntitySystems
 {
+    /// <summary>
+    ///     Entity system that manages <see cref="NodeGroupSystem"/> and <see cref="Node"/> updating.
+    /// </summary>
+    /// <seealso cref="NodeContainerSystem"/>
     [UsedImplicitly]
     public class NodeGroupSystem : EntitySystem
     {
-        [Dependency] private readonly IEntityManager _entityManager = default!;
-
         [Dependency] private readonly IPlayerManager _playerManager = default!;
         [Dependency] private readonly IAdminManager _adminManager = default!;
         [Dependency] private readonly INodeGroupFactory _nodeGroupFactory = default!;

Content.Server/NodeContainer/NodeGroups/BaseNodeGroup.cs

@@ -17,6 +17,9 @@ namespace Content.Server.NodeContainer.NodeGroups
     {
         bool Remaking { get; }
 
+        /// <summary>
+        ///     The list of nodes currently in this group.
+        /// </summary>
         IReadOnlyList<Node> Nodes { get; }
 
         void Create(NodeGroupID groupId);
@@ -41,6 +44,9 @@ namespace Content.Server.NodeContainer.NodeGroups
 
         IReadOnlyList<Node> INodeGroup.Nodes => Nodes;
 
+        /// <summary>
+        ///     The list of nodes in this group.
+        /// </summary>
         [ViewVariables] public readonly List<Node> Nodes = new();
 
         [ViewVariables] public int NodeCount => Nodes.Count;
@@ -54,6 +60,9 @@ namespace Content.Server.NodeContainer.NodeGroups
         [ViewVariables]
         protected GridId GridId { get; private set; }
 
+        /// <summary>
+        ///     Network ID of this group for client-side debug visualization of nodes.
+        /// </summary>
         [ViewVariables]
         public int NetId;
 
@@ -71,16 +80,35 @@ namespace Content.Server.NodeContainer.NodeGroups
             GridId = sourceNode.Owner.Transform.GridID;
         }
 
+        /// <summary>
+        ///     Called when a node has been removed from this group via deletion of the node.
+        /// </summary>
+        /// <remarks>
+        ///     Note that this always still results in a complete remake of the group later,
+        ///     but hooking this method is good for book keeping.
+        /// </remarks>
+        /// <param name="node">The node that was deleted.</param>
         public virtual void RemoveNode(Node node)
         {
         }
 
+        /// <summary>
+        ///     Called to load this newly created group up with new nodes.
+        /// </summary>
+        /// <param name="groupNodes">The new nodes for this group.</param>
         public virtual void LoadNodes(
             List<Node> groupNodes)
         {
             Nodes.AddRange(groupNodes);
         }
 
+        /// <summary>
+        ///     Called after the nodes in this group have been made into one or more new groups.
+        /// </summary>
+        /// <remarks>
+        ///     Use this to split in-group data such as pipe gas mixtures into newly split nodes.
+        /// </remarks>
+        /// <param name="newGroups">A list of new groups for this group's former nodes.</param>
         public virtual void AfterRemake(IEnumerable<IGrouping<INodeGroup?, Node>> newGroups) { }
 
         public void QueueRemake()

Content.Server/NodeContainer/Nodes/Node.cs

@@ -23,8 +23,14 @@ namespace Content.Server.NodeContainer.Nodes
         [DataField("nodeGroupID")]
         public NodeGroupID NodeGroupID { get; private set; } = NodeGroupID.Default;
 
+        /// <summary>
+        ///     The node group this node is a part of.
+        /// </summary>
         [ViewVariables] public INodeGroup? NodeGroup;
 
+        /// <summary>
+        ///     The entity that owns this node via its <see cref="NodeContainerComponent"/>.
+        /// </summary>
         [ViewVariables] public IEntity Owner { get; private set; } = default!;
 
         /// <summary>
@@ -43,24 +49,49 @@ namespace Content.Server.NodeContainer.Nodes
         /// </summary>
         public bool Deleting;
 
+        /// <summary>
+        ///     All compatible nodes that are reachable by this node.
+        ///     Effectively, active connections out of this node.
+        /// </summary>
         public readonly HashSet<Node> ReachableNodes = new();
 
         internal int FloodGen;
         internal int UndirectGen;
         internal bool FlaggedForFlood;
         internal int NetId;
+
+        /// <summary>
+        ///     Name of this node on the owning <see cref="NodeContainerComponent"/>.
+        /// </summary>
         public string Name = default!;
 
+        /// <summary>
+        ///     Invoked when the owning <see cref="NodeContainerComponent"/> is initialized.
+        /// </summary>
+        /// <param name="owner">The owning entity.</param>
         public virtual void Initialize(IEntity owner)
         {
             Owner = owner;
         }
 
+        /// <summary>
+        ///     Invoked when the owning <see cref="NodeContainerComponent"/> is started.
+        /// </summary>
         public virtual void OnContainerStartup()
         {
             EntitySystem.Get<NodeGroupSystem>().QueueReflood(this);
         }
 
+        /// <summary>
+        ///     Immediately create a single-node node group for this node if it does not have one yet.
+        /// </summary>
+        /// <remarks>
+        ///     This can be useful for nodes like pipes
+        ///     that need immediate access to their node group to set parameters like node volume.
+        ///     The node group created by this function (if necessary) will still update and form new,
+        ///     merged groups later if necessary.
+        ///     Set parameters like pipe net volume should then be transferred/merged there.
+        /// </remarks>
         public void CreateSingleNetImmediate()
         {
             EntitySystem.Get<NodeGroupSystem>().CreateSingleNetImmediate(this);
@@ -78,15 +109,24 @@ namespace Content.Server.NodeContainer.Nodes
             }
         }
 
+        /// <summary>
+        ///     Called when the anchored state of the owning entity changes.
+        /// </summary>
         public virtual void AnchorStateChanged()
         {
         }
 
+        /// <summary>
+        ///     Called after the parent node group has been rebuilt.
+        /// </summary>
         public virtual void OnPostRebuild()
         {
 
         }
 
+        /// <summary>
+        ///     Called when the owning <see cref="NodeContainerComponent"/> is shut down.
+        /// </summary>
         public virtual void OnContainerShutdown()
         {
             Deleting = true;
@@ -97,6 +137,14 @@ namespace Content.Server.NodeContainer.Nodes
         ///     How this node will attempt to find other reachable <see cref="Node"/>s to group with.
         ///     Returns a set of <see cref="Node"/>s to consider grouping with. Should not return this current <see cref="Node"/>.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// The set of nodes returned can be asymmetrical
+        /// (meaning that it can return other nodes whose <see cref="GetReachableNodes"/> does not return this node).
+        /// If this is used, creation of a new node may not correctly merge networks unless both sides
+        /// of this asymmetric relation are made to manually update with <see cref="NodeGroupSystem.QueueReflood"/>.
+        /// </para>
+        /// </remarks>
         public abstract IEnumerable<Node> GetReachableNodes();
     }
 }