Docs/cleanup for node system.

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();
     }
 }