diff --git a/CSharp/Libraries/UniversalEditor.Core/Accessor.cs b/CSharp/Libraries/UniversalEditor.Core/Accessor.cs index 3d5fcc58..2c9ed85a 100644 --- a/CSharp/Libraries/UniversalEditor.Core/Accessor.cs +++ b/CSharp/Libraries/UniversalEditor.Core/Accessor.cs @@ -7,25 +7,51 @@ using System.Diagnostics; namespace UniversalEditor { + /// + /// Provides the ability to access a -agnostic stream. s for + /// import and export may be used to allow the interactive user to specify -specific + /// parameters. + /// [DebuggerNonUserCode()] public abstract class Accessor : References { + /// + /// Creates or returns an existing object referring to this object. + /// + /// A object that can be used to create additional instances of this object. public virtual AccessorReference MakeReference() { return new AccessorReference(this.GetType()); } + /// + /// Creates a new instance of this and initializes the associated + /// and . + /// public Accessor() { mvarReader = new Reader(this); mvarWriter = new Writer(this); } + /// + /// Gets or sets the length of the data being accessed, if possible. + /// public abstract long Length { get; set; } + /// + /// Gets the position within the underlying stream, if possible. + /// + /// The position within the underlying stream protected abstract long GetPosition(); + /// + /// Gets or sets the position within the underlying stream, if possible. + /// public virtual long Position { get { return GetPosition(); } set { Seek(value, SeekOrigin.Begin); } } + /// + /// Determines how many bytes are remaining to be read from the underlying stream, if possible. + /// public long Remaining { get @@ -36,13 +62,45 @@ namespace UniversalEditor } } - public void Seek(int length, SeekOrigin position) + /// + /// Sets the position within the underlying stream based on the given relative position and origin. + /// + /// The location within the underlying stream relative to the given . + /// The reference point from where to seek. + public void Seek(int offset, SeekOrigin origin) { - Seek((long)length, position); + Seek((long)offset, origin); } - public abstract void Seek(long length, SeekOrigin position); + /// + /// Sets the position within the underlying stream based on the given relative position and origin. + /// + /// The location within the underlying stream relative to the given . + /// The reference point from where to seek. + public abstract void Seek(long offset, SeekOrigin origin); + /// + /// Reads the specified amount of bytes from the underlying stream into the specified buffer starting at the + /// specified offset. + /// + /// The buffer into which to read data. + /// The position in the buffer from which to start copying data. + /// The number of bytes to read from the underlying stream. + /// + /// The number of bytes actually read from the underlying stream. This may differ from the requested amount + /// due to encountering the end of stream or a network connection error. + /// protected internal abstract int ReadInternal(byte[] buffer, int start, int count); + /// + /// Writes the specified amount of bytes to the underlying stream from the specified buffer starting at the + /// specified offset. + /// + /// The buffer from which to write data. + /// The position in the buffer from which to start copying data. + /// The number of bytes to write to the underlying stream. + /// + /// The number of bytes actually written to the underlying stream. This may differ from the requested amount + /// due to lack of disk space or a network connection error. + /// protected internal abstract int WriteInternal(byte[] buffer, int start, int count); internal virtual void FlushInternal() @@ -50,8 +108,14 @@ namespace UniversalEditor } private bool mvarIsOpen = false; + /// + /// Determines whether this is currently open. + /// public bool IsOpen { get { return mvarIsOpen; } protected set { mvarIsOpen = value; } } + /// + /// Opens this . + /// public void Open() { if (mvarIsOpen) return; @@ -59,6 +123,10 @@ namespace UniversalEditor OpenInternal(); mvarIsOpen = true; } + /// + /// Closes this , making the underlying stream available to be re-opened by another + /// . + /// public void Close() { if (!mvarIsOpen) return; @@ -67,7 +135,13 @@ namespace UniversalEditor mvarIsOpen = false; } + /// + /// The internal implementation of the command. + /// protected abstract void OpenInternal(); + /// + /// The internal implementation of the command. + /// protected abstract void CloseInternal(); private Encoding mvarDefaultEncoding = Encoding.Default; @@ -77,18 +151,35 @@ namespace UniversalEditor public Encoding DefaultEncoding { get { return mvarDefaultEncoding; } set { mvarDefaultEncoding = value; } } private Reader mvarReader = null; + /// + /// A which reads from the underlying stream of this . + /// public Reader Reader { get { return mvarReader; } } private Writer mvarWriter = null; + /// + /// A which writes to the underlying stream of this . + /// public Writer Writer { get { return mvarWriter; } } + /// + /// The title of this . + /// public virtual string Title { get { return String.Empty; } } + /// + /// Gets the file name without path information for this , if applicable. + /// + /// A containing the file name without path information for this , if applicable. public virtual string GetFileTitle() { return String.Empty; } + /// + /// Gets the file name including path information for this , if applicable. + /// + /// A containing the file name including path information for this , if applicable. public virtual string GetFileName() { return String.Empty; diff --git a/CSharp/Libraries/UniversalEditor.Core/AccessorReference.cs b/CSharp/Libraries/UniversalEditor.Core/AccessorReference.cs index 27a07249..12da523a 100644 --- a/CSharp/Libraries/UniversalEditor.Core/AccessorReference.cs +++ b/CSharp/Libraries/UniversalEditor.Core/AccessorReference.cs @@ -31,10 +31,20 @@ namespace UniversalEditor private string mvarTitle = String.Empty; public string Title { get { return mvarTitle; } set { mvarTitle = value; } } + /// + /// Determines if this object should be filtered by the given criteria. + /// + /// The filter that determines whether this object should be displayed in a list of objects. + /// True if this object should appear in the list; false otherwise. public bool ShouldFilterObject(string filter) { return mvarTitle.ToLower().Contains(filter.ToLower()); } + + /// + /// Gets the detail fields that are shown in lists of this object in details view. + /// + /// An array of s that are shown in detail columns of lists of this object. public string[] GetDetails() { return new string[] { mvarTitle }; @@ -56,12 +66,17 @@ namespace UniversalEditor /// public CustomOption.CustomOptionCollection ExportOptions { get { return mvarExportOptions; } } - private CustomOption.CustomOptionCollection mvarImportOptions = new CustomOption.CustomOptionCollection();/// + private CustomOption.CustomOptionCollection mvarImportOptions = new CustomOption.CustomOptionCollection(); + /// /// A collection of s that are applied to the /// when it is being used to open or import a file. /// public CustomOption.CustomOptionCollection ImportOptions { get { return mvarImportOptions; } } + /// + /// Creates an instance of an from the described in this . + /// + /// An instance from the described in this . public Accessor Create() { if (mvarAccessorType == null && mvarAccessorTypeName != null) diff --git a/CSharp/Libraries/UniversalEditor.Core/Checksum/ChecksumModule.cs b/CSharp/Libraries/UniversalEditor.Core/Checksum/ChecksumModule.cs index d1a68b2b..6fb49b96 100644 --- a/CSharp/Libraries/UniversalEditor.Core/Checksum/ChecksumModule.cs +++ b/CSharp/Libraries/UniversalEditor.Core/Checksum/ChecksumModule.cs @@ -5,13 +5,27 @@ using System.Text; namespace UniversalEditor.Checksum { + /// + /// Provides the minimal functionality required to create a checksum calculation module. + /// public abstract class ChecksumModule { + /// + /// The name of this checksum calculation module. + /// public abstract string Name { get; } private long mvarValue = 0; + /// + /// The current value of the checksum being calculated. + /// public virtual long Value { get { return mvarValue; } protected set { mvarValue = value; } } + /// + /// Calculates the checksum based on the given input. + /// + /// The array of bytes used as input to the checksum calculation routine. + /// A that represents the checksum of the given input. public long Calculate(byte[] input) { Reset(); @@ -30,19 +44,26 @@ namespace UniversalEditor.Checksum /// /// Updates the checksum with the bytes taken from the array. /// - /// - /// buffer an array of bytes - /// + /// The array of bytes used as input to the checksum calculation routine. public void Update(byte[] buffer) { - if (buffer == null) - { - throw new ArgumentNullException("buffer"); - } - + if (buffer == null) throw new ArgumentNullException("buffer"); Update(buffer, 0, buffer.Length); } - public abstract void Update(byte[] buffer, int offset, int count); - public abstract void Update(int value); + + /// + /// Updates the checksum with a count of bytes taken from the array beginning at offset + /// . + /// + /// The array of bytes used as input to the checksum calculation routine. + /// The offset into from which calculation starts. + /// The number of bytes to use in the checksum calculation. + public abstract void Update(byte[] buffer, int offset, int count); + + /// + /// Calculates the checksum based on the given input. + /// + /// The value used as input to the checksum calculation routine. + public abstract void Update(int input); } } diff --git a/CSharp/Libraries/UniversalEditor.Core/Common/Path.cs b/CSharp/Libraries/UniversalEditor.Core/Common/Path.cs index 81fd2a0c..4caa95f3 100644 --- a/CSharp/Libraries/UniversalEditor.Core/Common/Path.cs +++ b/CSharp/Libraries/UniversalEditor.Core/Common/Path.cs @@ -4,8 +4,18 @@ using System.Text; namespace UniversalEditor.Common { + /// + /// Provides common path operations. + /// public static class Path { + /// + /// Generates an absolute path from the given relative (or absolute) path and a parent path. + /// + /// The relative (or absolute) path to make absolute. + /// The parent path of the given relative path. + /// A concatenation of the source path and the parent path if the source path is relative; otherwise, + /// just the source path. public static string MakeAbsolutePath(string sourcePath, string parentPath = null) { string result; @@ -26,8 +36,18 @@ namespace UniversalEditor.Common return result; } + /// + /// Generates a relative path from the specified absolute (or relative) path and parent directory name. + /// + /// The absolute (or relative) path to make relative. + /// The parent path for the relative path. + /// A substring of the relative path minus the parent path if the absolute path starts with the + /// parent path; otherwise, the relative (or absolute) path. public static string MakeRelativePath(string FileName, string DirectoryName) { + // This only goes "down" the folder hierarchy (e.g. C:/path/to/parent with C:/path as the parent becomes + // to/parent). Should we bother implementing "up" the hierarchy (will take some psychic powers) to allow + // us to use dot-dot paths (../../some/other/folder)? if (FileName.StartsWith(DirectoryName)) { return FileName.Substring(DirectoryName.Length); diff --git a/CSharp/Libraries/UniversalEditor.Core/ProgressEvent.cs b/CSharp/Libraries/UniversalEditor.Core/ProgressEvent.cs index 7ba56a97..3a1a19d2 100644 --- a/CSharp/Libraries/UniversalEditor.Core/ProgressEvent.cs +++ b/CSharp/Libraries/UniversalEditor.Core/ProgressEvent.cs @@ -6,24 +6,48 @@ using System.Text; namespace UniversalEditor { + /// + /// A delegate for the event that is raised when progress is made during an asynchronous operation. + /// + /// The control firing this event. + /// A that contains additional information about this event. public delegate void ProgressEventHandler(object sender, ProgressEventArgs e); + /// + /// Event arguments for the event that is raised when progress is made during an asynchronous operation. + /// public class ProgressEventArgs : CancelEventArgs { private long mvarTotal = 0; + /// + /// The total possible amount of progress represented by this progress event. + /// public long Total { get { return mvarTotal; } } private long mvarCurrent = 0; + /// + /// The current amount of progress completed. + /// public long Current { get { return mvarCurrent; } } + /// + /// The amount of progress remaining. + /// + public long Remaining { get { return mvarTotal - mvarCurrent; } } + private string mvarMessage = String.Empty; + /// + /// The progress message + /// public string Message { get { return mvarMessage; } } - public ProgressEventArgs(long current, long total) - { - mvarCurrent = current; - mvarTotal = total; - } - public ProgressEventArgs(long current, long total, string message) + /// + /// Creates a new instance of the event arguments for the event that is + /// raised when progress is made during an asynchronous operation. + /// + /// The current amount of progress completed. + /// The total possible amount of progress represented by this progress event. + /// The progress message + public ProgressEventArgs(long current, long total, string message = "") { mvarCurrent = current; mvarTotal = total; diff --git a/CSharp/Libraries/UniversalEditor.Core/References.cs b/CSharp/Libraries/UniversalEditor.Core/References.cs index 094a0577..36c5b28d 100644 --- a/CSharp/Libraries/UniversalEditor.Core/References.cs +++ b/CSharp/Libraries/UniversalEditor.Core/References.cs @@ -5,15 +5,40 @@ using System.Text; namespace UniversalEditor { + /// + /// Defines an object that references a object. + /// + /// The object referenced by this object. public interface References { + /// + /// Creates or returns an existing object referring to this object. + /// + /// A object that can be used to create additional instances of this object. TRef MakeReference(); } + /// + /// Defines an object that is referenced by the given object. + /// + /// The object which references this object. public interface ReferencedBy - { + { + /// + /// Creates an instance of this object from the described in the associated object. + /// + /// An instance of this object created from the described in the associated object. TObj Create(); - - string[] GetDetails(); + + /// + /// Gets the detail fields that are shown in lists of this object in details view. + /// + /// An array of s that are shown in detail columns of lists of this object. + string[] GetDetails(); + /// + /// Determines if this object should be filtered by the given criteria. + /// + /// The filter that determines whether this object should be displayed in a list of objects. + /// True if this object should appear in the list; false otherwise. bool ShouldFilterObject(string filter); } }