More documentation, fully CLI-compliant.

Substrate/SubstrateCS/Source/AlphaBlock.cs

@@ -146,6 +146,9 @@ namespace Substrate
             _tileEntity = te;
         }
 
+        /// <summary>
+        /// Creates a default Tile Entity record appropriate for the block.
+        /// </summary>
         public void CreateTileEntity ()
         {
             BlockInfoEx info = BlockInfo.BlockTable[_id] as BlockInfoEx;

Substrate/SubstrateCS/Source/AlphaBlockRef.cs

@@ -35,6 +35,9 @@ namespace Substrate
             _index = index;
         }
 
+        /// <summary>
+        /// Checks if this object is currently a valid ref into another <see cref="AlphaBlockCollection"/>.
+        /// </summary>
         public bool IsValid
         {
             get { return _collection != null; }
@@ -140,6 +143,9 @@ namespace Substrate
             _collection.SetTileEntity(_index, te);
         }
 
+        /// <summary>
+        /// Creates a default Tile Entity record appropriate for the block.
+        /// </summary>
         public void CreateTileEntity ()
         {
             _collection.CreateTileEntity(_index);

Substrate/SubstrateCS/Source/BlockManager.cs

@@ -3,6 +3,9 @@ using Substrate.Core;
 
 namespace Substrate
 {
+    /// <summary>
+    /// Represents an Alpha-compatible interface for globally managing blocks.
+    /// </summary>
     public class BlockManager : IBlockManager
     {
         public const int MIN_X = -32000000;
@@ -29,18 +32,28 @@ namespace Substrate
         private bool _autoLight = true;
         private bool _autoFluid = false;
 
+        /// <summary>
+        /// Gets or sets a value indicating whether changes to blocks will trigger automatic lighting updates.
+        /// </summary>
         public bool AutoLight
         {
             get { return _autoLight; }
             set { _autoLight = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether changes to blocks will trigger automatic fluid updates.
+        /// </summary>
         public bool AutoFluid
         {
             get { return _autoFluid; }
             set { _autoFluid = value; }
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="BlockManager"/> instance on top of the given <see cref="IChunkManager"/>.
+        /// </summary>
+        /// <param name="cm">An <see cref="IChunkManager"/> instance.</param>
         public BlockManager (IChunkManager cm)
         {
             chunkMan = cm;
@@ -58,6 +71,15 @@ namespace Substrate
             chunkZLog = Log2(chunkZDim);
         }
 
+        /// <summary>
+        /// Returns a new <see cref="AlphaBlock"/> object from global coordinates.
+        /// </summary>
+        /// <param name="x">Global X-coordinate of block.</param>
+        /// <param name="y">Global Y-coordinate of block.</param>
+        /// <param name="z">Global Z-coordiante of block.</param>
+        /// <returns>A new <see cref="AlphaBlock"/> object representing context-independent data of a single block.</returns>
+        /// <remarks>Context-independent data excludes data such as lighting.  <see cref="AlphaBlock"/> object actually contain a copy
+        /// of the data they represent, so changes to the <see cref="AlphaBlock"/> will not affect this container, and vice-versa.</remarks>
         public AlphaBlock GetBlock (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -68,6 +90,16 @@ namespace Substrate
             return cache.Blocks.GetBlock(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <summary>
+        /// Returns a new <see cref="AlphaBlockRef"/> object from global coordaintes.
+        /// </summary>
+        /// <param name="x">Global X-coordinate of block.</param>
+        /// <param name="y">Global Y-coordinate of block.</param>
+        /// <param name="z">Global Z-coordinate of block.</param>
+        /// <returns>A new <see cref="AlphaBlockRef"/> object representing context-dependent data of a single block.</returns>
+        /// <remarks>Context-depdendent data includes all data associated with this block.  Since a <see cref="AlphaBlockRef"/> represents
+        /// a view of a block within this container, any updates to data in the container will be reflected in the <see cref="AlphaBlockRef"/>,
+        /// and vice-versa for updates to the <see cref="AlphaBlockRef"/>.</remarks>
         public AlphaBlockRef GetBlockRef (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -78,6 +110,13 @@ namespace Substrate
             return cache.Blocks.GetBlockRef(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <summary>
+        /// Updates a block with values from a <see cref="AlphaBlock"/> object.
+        /// </summary>
+        /// <param name="x">Global X-coordinate of a block.</param>
+        /// <param name="y">Global Y-coordinate of a block.</param>
+        /// <param name="z">Global Z-coordinate of a block.</param>
+        /// <param name="block">A <see cref="AlphaBlock"/> object to copy block data from.</param>
         public void SetBlock (int x, int y, int z, AlphaBlock block)
         {
             cache = GetChunk(x, y, z);
@@ -88,6 +127,13 @@ namespace Substrate
             cache.Blocks.SetBlock(x & chunkXMask, y & chunkYMask, z & chunkZMask, block);
         }
 
+        /// <summary>
+        /// Gets a reference object to a single chunk given global coordinates to a block within that chunk.
+        /// </summary>
+        /// <param name="x">Global X-coordinate of a block.</param>
+        /// <param name="y">Global Y-coordinate of a block.</param>
+        /// <param name="z">Global Z-coordinate of a block.</param>
+        /// <returns>A <see cref="ChunkRef"/> to a single chunk containing the given block.</returns>
         protected ChunkRef GetChunk (int x, int y, int z)
         {
             x >>= chunkXLog;
@@ -129,11 +175,13 @@ namespace Substrate
             return GetBlockRef(x, y, z);
         }
 
+        /// <inheritdoc/>
         public void SetBlock (int x, int y, int z, IBlock block)
         {
             cache.Blocks.SetBlock(x, y, z, block);
         }
 
+        /// <inheritdoc/>
         public BlockInfo GetInfo (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -144,6 +192,7 @@ namespace Substrate
             return cache.Blocks.GetInfo(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public int GetID (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -154,6 +203,7 @@ namespace Substrate
             return cache.Blocks.GetID(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void SetID (int x, int y, int z, int id)
         {
             cache = GetChunk(x, y, z);
@@ -188,11 +238,13 @@ namespace Substrate
             return GetBlockRef(x, y, z);
         }
 
+        /// <inheritdoc/>
         public void SetBlock (int x, int y, int z, IDataBlock block)
         {
             cache.Blocks.SetBlock(x, y, z, block);
         }
 
+        /// <inheritdoc/>
         public int GetData (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -203,6 +255,7 @@ namespace Substrate
             return cache.Blocks.GetData(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void SetData (int x, int y, int z, int data)
         {
             cache = GetChunk(x, y, z);
@@ -228,11 +281,13 @@ namespace Substrate
             return GetBlockRef(x, y, z);
         }
 
+        /// <inheritdoc/>
         public void SetBlock (int x, int y, int z, ILitBlock block)
         {
             cache.Blocks.SetBlock(x, y, z, block);
         }
 
+        /// <inheritdoc/>
         public int GetBlockLight (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -243,6 +298,7 @@ namespace Substrate
             return cache.Blocks.GetBlockLight(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public int GetSkyLight (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -253,6 +309,7 @@ namespace Substrate
             return cache.Blocks.GetSkyLight(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void SetBlockLight (int x, int y, int z, int light)
         {
             cache = GetChunk(x, y, z);
@@ -263,6 +320,7 @@ namespace Substrate
             cache.Blocks.SetBlockLight(x & chunkXMask, y & chunkYMask, z & chunkZMask, light);
         }
 
+        /// <inheritdoc/>
         public void SetSkyLight (int x, int y, int z, int light)
         {
             cache = GetChunk(x, y, z);
@@ -273,6 +331,7 @@ namespace Substrate
             cache.Blocks.SetSkyLight(x & chunkXMask, y & chunkYMask, z & chunkZMask, light);
         }
 
+        /// <inheritdoc/>
         public int GetHeight (int x, int z)
         {
             cache = GetChunk(x, 0, z);
@@ -283,6 +342,7 @@ namespace Substrate
             return cache.Blocks.GetHeight(x & chunkXMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void SetHeight (int x, int z, int height)
         {
             cache = GetChunk(x, 0, z);
@@ -293,6 +353,7 @@ namespace Substrate
             cache.Blocks.SetHeight(x & chunkXMask, z & chunkZMask, height);
         }
 
+        /// <inheritdoc/>
         public void UpdateBlockLight (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -303,6 +364,7 @@ namespace Substrate
             cache.Blocks.UpdateBlockLight(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void UpdateSkyLight (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -328,11 +390,13 @@ namespace Substrate
             return GetBlockRef(x, y, z);
         }
 
+        /// <inheritdoc/>
         public void SetBlock (int x, int y, int z, IPropertyBlock block)
         {
             cache.Blocks.SetBlock(x, y, z, block);
         }
 
+        /// <inheritdoc/>
         public TileEntity GetTileEntity (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -343,6 +407,7 @@ namespace Substrate
             return cache.Blocks.GetTileEntity(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void SetTileEntity (int x, int y, int z, TileEntity te)
         {
             cache = GetChunk(x, y, z);
@@ -353,6 +418,7 @@ namespace Substrate
             cache.Blocks.SetTileEntity(x & chunkXMask, y & chunkYMask, z & chunkZMask, te);
         }
 
+        /// <inheritdoc/>
         public void CreateTileEntity (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);
@@ -363,6 +429,7 @@ namespace Substrate
             cache.Blocks.CreateTileEntity(x & chunkXMask, y & chunkYMask, z & chunkZMask);
         }
 
+        /// <inheritdoc/>
         public void ClearTileEntity (int x, int y, int z)
         {
             cache = GetChunk(x, y, z);

Substrate/SubstrateCS/Source/Core/ChunkFile.cs

@@ -30,17 +30,17 @@ namespace Substrate.Core
             string dir1 = Base36.Encode(cx % 64);
             string dir2 = Base36.Encode(cz % 64);
 
-            _filename = Path.Combine(path, dir1);
+            FileName = Path.Combine(path, dir1);
-            if (!Directory.Exists(_filename)) {
+            if (!Directory.Exists(FileName)) {
-                Directory.CreateDirectory(_filename);
+                Directory.CreateDirectory(FileName);
             }
 
-            _filename = Path.Combine(_filename, dir2);
+            FileName = Path.Combine(FileName, dir2);
-            if (!Directory.Exists(_filename)) {
+            if (!Directory.Exists(FileName)) {
-                Directory.CreateDirectory(_filename);
+                Directory.CreateDirectory(FileName);
             }
 
-            _filename = Path.Combine(_filename, file);
+            FileName = Path.Combine(FileName, file);
         }
     }
 }

Substrate/SubstrateCS/Source/Core/Interface.cs

@@ -4,8 +4,16 @@ using System.Text;
 
 namespace Substrate.Core
 {
+    /// <summary>
+    /// Provides a virtual deep copy capability to implementors.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
     public interface ICopyable <T>
     {
+        /// <summary>
+        /// Performs a virtual deep copy of the object instance.
+        /// </summary>
+        /// <returns>An independent copy of the object instance.</returns>
         T Copy ();
     }
 }

Substrate/SubstrateCS/Source/Core/NBTFile.cs

@@ -9,13 +9,19 @@ namespace Substrate.Core
 {
     public class NBTFile
     {
-        protected string _filename;
+        private string _filename;
 
         public NBTFile (string path)
         {
             _filename = path;
         }
 
+        public string FileName
+        {
+            get { return _filename; }
+            protected set { _filename = value; }
+        }
+
         public bool Exists ()
         {
             return File.Exists(_filename);

Substrate/SubstrateCS/Source/Core/NibbleArray.cs

@@ -7,7 +7,7 @@ namespace Substrate.Core
 
     public class NibbleArray : ICopyable<NibbleArray>
     {
-        protected readonly byte[] _data = null;
+        private readonly byte[] _data = null;
 
         public NibbleArray (int length)
         {
@@ -56,6 +56,11 @@ namespace Substrate.Core
             }
         }
 
+        protected byte[] Data
+        {
+            get { return _data; }
+        }
+
         public void Clear ()
         {
             for (int i = 0; i < _data.Length; i++)
@@ -138,8 +143,8 @@ namespace Substrate.Core
 
         public override NibbleArray Copy ()
         {
-            byte[] data = new byte[_data.Length];
+            byte[] data = new byte[Data.Length];
-            _data.CopyTo(data, 0);
+            Data.CopyTo(data, 0);
 
             return new XZYNibbleArray(_xdim, _ydim, _zdim, data);
         }

Substrate/SubstrateCS/Source/Core/PlayerFile.cs

@@ -21,7 +21,7 @@ namespace Substrate.Core
             }
 
             string file = name + ".dat";
-            _filename = Path.Combine(path, file);
+            FileName = Path.Combine(path, file);
         }
     }
 }

Substrate/SubstrateCS/Source/ImportExport/Schematic.cs

@@ -6,6 +6,9 @@ using Substrate.Nbt;
 
 namespace Substrate.ImportExport
 {
+    /// <summary>
+    /// Provides import and export support for the 3rd party schematic file format.
+    /// </summary>
     public class Schematic
     {
         private static SchemaNodeCompound _schema = new SchemaNodeCompound()
@@ -36,12 +39,23 @@ namespace Substrate.ImportExport
         {
         }
 
+        /// <summary>
+        /// Create an exportable schematic wrapper around existing blocks and entities.
+        /// </summary>
+        /// <param name="blocks">An existing <see cref="AlphaBlockCollection"/>.</param>
+        /// <param name="entities">An existing <see cref="EntityCollection"/>.</param>
         public Schematic (AlphaBlockCollection blocks, EntityCollection entities)
         {
             _blockset = blocks;
             _entityset = entities;
         }
 
+        /// <summary>
+        /// Create an empty, exportable schematic of given dimensions.
+        /// </summary>
+        /// <param name="xdim">The length of the X-dimension in blocks.</param>
+        /// <param name="ydim">The length of the Y-dimension in blocks.</param>
+        /// <param name="zdim">The length of the Z-dimension in blocks.</param>
         public Schematic (int xdim, int ydim, int zdim)
         {
             _blocks = new XZYByteArray(xdim, ydim, zdim);
@@ -59,12 +73,18 @@ namespace Substrate.ImportExport
 
         #region Properties
 
+        /// <summary>
+        /// Gets or sets the underlying block collection.
+        /// </summary>
         public AlphaBlockCollection Blocks
         {
             get { return _blockset; }
             set { _blockset = value; }
         }
 
+        /// <summary>
+        /// Gets or sets the underlying entity collection.
+        /// </summary>
         public EntityCollection Entities
         {
             get { return _entityset; }
@@ -73,6 +93,11 @@ namespace Substrate.ImportExport
 
         #endregion
 
+        /// <summary>
+        /// Imports a schematic file at the given path and returns in as a <see cref="Schematic"/> object.
+        /// </summary>
+        /// <param name="path">The path to the schematic file.</param>
+        /// <returns>A <see cref="Schematic"/> object containing the decoded schematic file data.</returns>
         public static Schematic Import (string path)
         {
             NBTFile schematicFile = new NBTFile(path);
@@ -128,6 +153,10 @@ namespace Substrate.ImportExport
             return self;
         }
 
+        /// <summary>
+        /// Exports the <see cref="Schematic"/> object to a schematic file.
+        /// </summary>
+        /// <param name="path">The path to write out the schematic file to.</param>
         public void Export (string path)
         {
             int xdim = _blockset.XDim;

Substrate/SubstrateCS/Source/Nbt/NbtIOException.cs

@@ -6,7 +6,7 @@ namespace Substrate.Nbt
     /// <summary>
     /// The exception that is thrown when errors occur during Nbt IO operations.
     /// </summary>
-    /// <remarks>In most cases, the <see cref="InnerException"/> property will contain more detailed information on the
+    /// <remarks>In most cases, the <see cref="NbtIOException.InnerException"/> property will contain more detailed information on the
     /// error that occurred.</remarks>
     [Serializable]
     public class NbtIOException : SubstrateException

Substrate/SubstrateCS/Source/Region.cs

@@ -555,6 +555,9 @@ namespace Substrate
             return chunk.Save(GetChunkOutStream(ForeignX(chunk.X), ForeignZ(chunk.Z)));
         }
 
+        /// <summary>
+        /// Checks if this container supports delegating an action on out-of-bounds coordinates to another container. 
+        /// </summary>
         public bool CanDelegateCoordinates
         {
             get { return true; }