Documentation

Substrate/SubstrateCS/Source/Chunk.cs

@@ -7,12 +7,21 @@ namespace Substrate
     using NBT;
     using Utility;
 
+    /// <summary>
+    /// A Minecraft Alpha-compatible chunk data structure.
+    /// </summary>
+    /// <remarks>
+    /// A Chunk internally wraps an NBT_Tree of raw chunk data.  Modifying the chunk will update the tree, and vice-versa.
+    /// </remarks>
     public class Chunk : IChunk, INBTObject<Chunk>, ICopyable<Chunk>
     {
         private const int XDIM = 16;
         private const int YDIM = 128;
         private const int ZDIM = 16;
 
+        /// <summary>
+        /// An NBT Schema definition for valid chunk data.
+        /// </summary>
         public static NBTCompoundNode LevelSchema = new NBTCompoundNode()
         {
             new NBTCompoundNode("Level")
@@ -48,41 +57,66 @@ namespace Substrate
         private AlphaBlockCollection _blockManager;
         private EntityCollection _entityManager;
 
+        /// <summary>
+        /// Gets the global X-coordinate of the chunk.
+        /// </summary>
         public int X
         {
             get { return _cx; }
         }
 
+        /// <summary>
+        /// Gets the global Z-coordinate of the chunk.
+        /// </summary>
         public int Z
         {
             get { return _cz; }
         }
 
+        /// <summary>
+        /// Gets the collection of all blocks and their data stored in the chunk.
+        /// </summary>
         public AlphaBlockCollection Blocks
         {
             get { return _blockManager; }
         }
 
+        /// <summary>
+        /// Gets the collection of all entities stored in the chunk.
+        /// </summary>
         public EntityCollection Entities
         {
             get { return _entityManager; }
         }
 
+        /// <summary>
+        /// Provides raw access to the underlying NBT_Tree.
+        /// </summary>
         public NBT_Tree Tree
         {
             get { return _tree; }
         }
 
+        /// <summary>
+        /// Gets or sets the chunk's TerrainPopulated status.
+        /// </summary>
         public bool IsTerrainPopulated
         {
             get { return _tree.Root["Level"].ToTagCompound()["TerrainPopulated"].ToTagByte() == 1; }
             set { _tree.Root["Level"].ToTagCompound()["TerrainPopulated"].ToTagByte().Data = (byte)(value ? 1 : 0); }
         }
 
+
         private Chunk ()
         {
         }
 
+        /// <summary>
+        /// Creates a default (empty) chunk.
+        /// </summary>
+        /// <param name="x">Global X-coordinate of the chunk.</param>
+        /// <param name="z">Global Z-coordinate of the chunk.</param>
+        /// <returns>A new Chunk object.</returns>
         public static Chunk Create (int x, int z)
         {
             Chunk c = new Chunk();
@@ -95,6 +129,11 @@ namespace Substrate
             return c;
         }
 
+        /// <summary>
+        /// Creates a chunk object from an existing NBT_Tree.
+        /// </summary>
+        /// <param name="tree">An NBT_Tree conforming to the chunk schema definition.</param>
+        /// <returns>A new Chunk object wrapping an existing NBT_Tree.</returns>
         public static Chunk Create (NBT_Tree tree)
         {
             Chunk c = new Chunk();
@@ -102,6 +141,11 @@ namespace Substrate
             return c.LoadTree(tree.Root);
         }
 
+        /// <summary>
+        /// Creates a chunk object from a verified NBT_Tree.
+        /// </summary>
+        /// <param name="tree">An NBT_Tree conforming to the chunk schema definition.</param>
+        /// <returns>A new Chunk object wrapping an existing NBT_Tree, or null on verification failure.</returns>
         public static Chunk CreateVerified (NBT_Tree tree)
         {
             Chunk c = new Chunk();
@@ -109,12 +153,22 @@ namespace Substrate
             return c.LoadTreeSafe(tree.Root);
         }
 
+        /// <summary>
+        /// Updates the chunk's global world coordinates.
+        /// </summary>
+        /// <param name="x">Global X-coordinate.</param>
+        /// <param name="z">Global Z-coordinate.</param>
         public virtual void SetLocation (int x, int z)
         {
             _cx = x;
             _cz = z;
         }
 
+        /// <summary>
+        /// Saves a Chunk's underlying NBT_Tree to an output stream.
+        /// </summary>
+        /// <param name="outStream">An open, writable output stream.</param>
+        /// <returns>True if the data is written out to the stream.</returns>
         public bool Save (Stream outStream)
         {
             if (outStream == null || !outStream.CanWrite) {
@@ -130,6 +184,11 @@ namespace Substrate
 
         #region INBTObject<Chunk> Members
 
+        /// <summary>
+        /// Loads the Chunk from an NBT tree rooted at the given TagValue node.
+        /// </summary>
+        /// <param name="tree">Root node of an NBT tree.</param>
+        /// <returns>A reference to the current Chunk, or null if the tree is unparsable.</returns>
         public Chunk LoadTree (TagValue tree)
         {
             TagCompound ctree = tree as TagCompound;
@@ -176,6 +235,11 @@ namespace Substrate
             return this;
         }
 
+        /// <summary>
+        /// Loads the Chunk from a validated NBT tree rooted at the given TagValue node.
+        /// </summary>
+        /// <param name="tree">Root node of an NBT tree.</param>
+        /// <returns>A reference to the current Chunk, or null if the tree does not conform to the chunk's NBT Schema definition.</returns>
         public Chunk LoadTreeSafe (TagValue tree)
         {
             if (!ValidateTree(tree)) {
@@ -185,11 +249,20 @@ namespace Substrate
             return LoadTree(tree);
         }
 
+        /// <summary>
+        /// Gets a valid NBT tree representing the Chunk.
+        /// </summary>
+        /// <returns>The root node of the Chunk's NBT tree.</returns>
         public TagValue BuildTree ()
         {
             return _tree.Root;
         }
 
+        /// <summary>
+        /// Validates an NBT tree against the chunk's NBT schema definition.
+        /// </summary>
+        /// <param name="tree">The root node of the NBT tree to verify.</param>
+        /// <returns>Status indicating if the tree represents a valid chunk.</returns>
         public bool ValidateTree (TagValue tree)
         {
             NBTVerifier v = new NBTVerifier(tree, LevelSchema);
@@ -201,6 +274,10 @@ namespace Substrate
 
         #region ICopyable<Chunk> Members
 
+        /// <summary>
+        /// Creates a deep copy of the Chunk and its underlying NBT tree.
+        /// </summary>
+        /// <returns>A new Chunk with copied data.</returns>
         public Chunk Copy ()
         {
             return Chunk.Create(_tree.Copy());

Substrate/SubstrateCS/Source/ChunkRef.cs

@@ -5,9 +5,11 @@ using System.Collections.Generic;
 namespace Substrate
 {
     /// <summary>
-    /// Provides a wrapper around a physical Chunk stored in a chunk container.  Modifying data in a ChunkRef will signal to the chunk 
-    /// container that the physical chunk needs to be saved.
+    /// Provides a wrapper around a physical Chunk stored in a chunk container.
     /// </summary>
+    /// <remarks>
+    /// Modifying data in a ChunkRef will signal to the chunk container that the physical chunk needs to be saved.
+    /// </remarks>
     public class ChunkRef : IChunk
     {
         private IChunkContainer _container;