Add missing summary comments in many places.

Author: jfreilly

src/BZip2/BZip2InputStream.cs

@@ -157,6 +157,7 @@ public override void Flush()
 		/// </summary>
 		/// <param name="offset">A byte offset relative to the <paramref name="origin"/> parameter.</param>
 		/// <param name="origin">A value of type <see cref="SeekOrigin"/> indicating the reference point used to obtain the new position.</param>
+		/// <returns>The new position of the stream.</returns>
 		/// <exception cref="NotSupportedException">Any access</exception>
 		public override long Seek(long offset, SeekOrigin origin)
 		{

src/BZip2/BZip2OutputStream.cs

@@ -193,6 +193,9 @@ public override long Position {
 		/// <summary>
 		/// Sets the current position of this stream to the given value.
 		/// </summary>
+		/// <param name="offset">The point relative to the offset from which to being seeking.</param>
+		/// <param name="origin">The reference point from which to begin seeking.</param>
+		/// <returns>The new position in the stream.</returns>
 		public override long Seek(long offset, SeekOrigin origin)
 		{
 			throw new NotSupportedException("BZip2OutputStream Seek not supported");
@@ -201,6 +204,7 @@ public override long Seek(long offset, SeekOrigin origin)
 		/// <summary>
 		/// Sets the length of this stream to the given value.
 		/// </summary>
+		/// <param name="value">The new stream length.</param>
 		public override void SetLength(long value)
 		{
 			throw new NotSupportedException("BZip2OutputStream SetLength not supported");
@@ -209,6 +213,7 @@ public override void SetLength(long value)
 		/// <summary>
 		/// Read a byte from the stream advancing the position.
 		/// </summary>
+		/// <returns>The byte read cast to an int; -1 if end of stream.</returns>
 		public override int ReadByte()
 		{
 			throw new NotSupportedException("BZip2OutputStream ReadByte not supported");
@@ -217,6 +222,12 @@ public override int ReadByte()
 		/// <summary>
 		/// Read a block of bytes
 		/// </summary>
+		/// <param name="buffer">The buffer to read into.</param>
+		/// <param name="offset">The offset in the buffer to start storing data at.</param>
+		/// <param name="count">The maximum number of bytes to read.</param>
+		/// <returns>The total number of bytes read. This might be less than the number of bytes
+		/// requested if that number of bytes are not currently available, or zero 
+		/// if the end of the stream is reached.</returns>
 		public override int Read(byte[] buffer, int offset, int count)
 		{
 			throw new NotSupportedException("BZip2OutputStream Read not supported");
@@ -225,6 +236,9 @@ public override int Read(byte[] buffer, int offset, int count)
 		/// <summary>
 		/// Write a block of bytes to the stream
 		/// </summary>
+		/// <param name="buffer">The buffer containing data to write.</param>
+		/// <param name="offset">The offset of the first byte to write.</param>
+		/// <param name="count">The number of bytes to write.</param>
 		public override void Write(byte[] buffer, int offset, int count)
 		{
 			if ( buffer == null ) {
@@ -254,6 +268,7 @@ public override void Write(byte[] buffer, int offset, int count)
 		/// <summary>
 		/// Write a byte to the stream.
 		/// </summary>
+		/// <param name="value">The byte to write to the stream.</param>
 		public override void WriteByte(byte value)
 		{
 			int b = (256 + value) % 256;

src/Encryption/PkzipClassic.cs

@@ -55,6 +55,7 @@ public abstract class PkzipClassic : SymmetricAlgorithm
 		/// Generates new encryption keys based on given seed
 		/// </summary>
 		/// <param name="seed">The seed value to initialise keys with.</param>
+		/// <returns>A new key value.</returns>
 		static public byte[] GenerateKeys(byte[] seed)
 		{
 			if ( seed == null ) 
@@ -68,10 +69,10 @@ static public byte[] GenerateKeys(byte[] seed)
 			}
 
 			uint[] newKeys = new uint[] {
-			                            0x12345678,
-			                            0x23456789,
-			                            0x34567890
-			                         };
+				0x12345678,
+				0x23456789,
+				0x34567890
+			 };
 
 			for (int i = 0; i < seed.Length; ++i) 
 			{

src/Tar/TarBuffer.cs

@@ -103,6 +103,8 @@ or which contains garbage records after a zero block.
 		/// <summary>
 		/// Get the record size for this buffer
 		/// </summary>
+		/// <value>The record size in bytes.
+		/// This is equal to the <see cref="BlockFactor"/> multiplied by the <see cref="BlockSize"/></value>
 		public int RecordSize 
 		{
 			get { 
@@ -113,6 +115,8 @@ public int RecordSize
 		/// <summary>
 		/// Get the TAR Buffer's record size.
 		/// </summary>
+		/// <returns>The record size in bytes.
+		/// This is equal to the <see cref="BlockFactor"/> multiplied by the <see cref="BlockSize"/></returns>
 		[Obsolete("Use RecordSize property instead")]
 		public int GetRecordSize()
 		{
@@ -122,6 +126,7 @@ public int GetRecordSize()
 		/// <summary>
 		/// Get the Blocking factor for the buffer
 		/// </summary>
+		/// <value>This is the number of block in each record.</value>
 		public int BlockFactor {
 			get { 
 				return blockFactor; 
@@ -131,6 +136,7 @@ public int BlockFactor {
 		/// <summary>
 		/// Get the TAR Buffer's block factor
 		/// </summary>
+		/// <returns>The block factor; the number of blocks per record.</returns>
 		[Obsolete("Use BlockFactor property instead")]
 		public int GetBlockFactor()
 		{
@@ -148,7 +154,7 @@ protected TarBuffer()
 		/// Create TarBuffer for reading with default BlockFactor
 		/// </summary>
 		/// <param name="inputStream">Stream to buffer</param>
-		/// <returns>TarBuffer</returns>
+		/// <returns>A new <see cref="TarBuffer"/> suitable for input.</returns>
 		public static TarBuffer CreateInputTarBuffer(Stream inputStream)
 		{
 			if ( inputStream == null )
@@ -164,7 +170,7 @@ public static TarBuffer CreateInputTarBuffer(Stream inputStream)
 		/// </summary>
 		/// <param name="inputStream">Stream to buffer</param>
 		/// <param name="blockFactor">Blocking factor to apply</param>
-		/// <returns>TarBuffer</returns>
+		/// <returns>A new <see cref="TarBuffer"/> suitable for input.</returns>
 		public static TarBuffer CreateInputTarBuffer(Stream inputStream, int blockFactor)
 		{
 			if ( inputStream == null )
@@ -193,7 +199,7 @@ public static TarBuffer CreateInputTarBuffer(Stream inputStream, int blockFactor
 		/// Construct TarBuffer for writing with default BlockFactor
 		/// </summary>
 		/// <param name="outputStream">output stream for buffer</param>
-		/// <returns>TarBuffer</returns>
+		/// <returns>A new <see cref="TarBuffer"/> suitable for output.</returns>
 		public static TarBuffer CreateOutputTarBuffer(Stream outputStream)
 		{
 			if ( outputStream == null )
@@ -209,7 +215,7 @@ public static TarBuffer CreateOutputTarBuffer(Stream outputStream)
 		/// </summary>
 		/// <param name="outputStream">Output stream to write to.</param>
 		/// <param name="blockFactor">Blocking factor to apply</param>
-		/// <returns>TarBuffer</returns>
+		/// <returns>A new <see cref="TarBuffer"/> suitable for output.</returns>
 		public static TarBuffer CreateOutputTarBuffer(Stream outputStream, int blockFactor)
 		{
 			if ( outputStream == null )
@@ -263,6 +269,7 @@ void Initialize(int blockFactor)
 		/// and also partial records
 		/// </summary>
 		/// <param name = "block">The data block to check.</param>
+		/// <returns>Returns true if the block is an EOF block; false otherwise.</returns>
 		public bool IsEOFBlock(byte[] block)
 		{
 			if ( block == null ) {

src/Tar/TarEntry.cs

@@ -124,6 +124,8 @@ public object Clone()
 		/// Construct an entry with only a <paramref name="name">name</paramref>.
 		/// This allows the programmer to construct the entry's header "by hand". 
 		/// </summary>
+		/// <param name="name">The name to use for the entry</param>
+		/// <returns>Returns the newly created <see cref="TarEntry"/></returns>
 		public static TarEntry CreateTarEntry(string name)
 		{
 			TarEntry entry = new TarEntry();
@@ -135,9 +137,8 @@ public static TarEntry CreateTarEntry(string name)
 		/// Construct an entry for a file. File is set to file, and the
 		/// header is constructed from information from the file.
 		/// </summary>
-		/// <param name = "fileName">
-		/// The file that the entry represents.
-		/// </param>
+		/// <param name = "fileName">The file name that the entry represents.</param>
+		/// <returns>Returns the newly created <see cref="TarEntry"/></returns>
 		public static TarEntry CreateEntryFromFile(string fileName)
 		{
 			TarEntry entry = new TarEntry();
@@ -149,8 +150,9 @@ public static TarEntry CreateEntryFromFile(string fileName)
 		/// Determine if the two entries are equal. Equality is determined
 		/// by the header names being equal.
 		/// </summary>
+		/// <param name="obj">The <see cref="Object"/> to compare with the current Object.</param>
 		/// <returns>
-		/// True if the entries are equal.
+		/// True if the entries are equal; false if not.
 		/// </returns>
 		public override bool Equals(object obj)
 		{
@@ -164,8 +166,9 @@ public override bool Equals(object obj)
 		}
 
 		/// <summary>
-		/// Must be overridden when you override Equals.
+		/// Derive a Hash value for the current <see cref="Object"/>
 		/// </summary>
+		/// <returns>A Hash code for the current <see cref="Object"/></returns>
 		public override int GetHashCode()
 		{
 			return Name.GetHashCode();

src/Tar/TarHeader.cs

@@ -36,7 +36,7 @@
 
 /* The tar format and its POSIX successor PAX have a long history which makes for compatability
    issues when creating and reading files.
-   
+
    This is further complicated by a large number of programs with variations on formats
    One common issue is the handling of names longer than 100 characters.
    GNU style long names are currently supported.
@@ -547,8 +547,9 @@ public int DevMinor
 
 		#region ICloneable Members
 		/// <summary>
-		/// Clone a TAR header.
+		/// Create a new <see cref="TarHeader"/> that is a copy of the current instance.
 		/// </summary>
+		/// <returns>A new <see cref="Object"/> that is a copy of the current instance.</returns>
 		public object Clone()
 		{
 			return this.MemberwiseClone();
@@ -963,10 +964,10 @@ public static int GetAsciiBytes(string toAdd, int nameOffset, byte[] buffer, int
 			}
 
 			for (int i = 0 ; i < length && nameOffset + i < toAdd.Length; ++i) 
-		 	{
+			{
 				buffer[bufferOffset + i] = (byte)toAdd[nameOffset + i];
-		 	}
-		 	return bufferOffset + length;
+			}
+			return bufferOffset + length;
 		}
 
 		/// <summary>

src/Tar/TarInputStream.cs

@@ -136,6 +136,9 @@ public override void Flush()
 		/// <summary>
 		/// Set the streams position.  This operation is not supported and will throw a NotSupportedException
 		/// </summary>
+		/// <param name="offset">The offset relative to the origin to seek to.</param>
+		/// <param name="origin">The <see cref="SeekOrigin"/> to start seeking from.</param>
+		/// <returns>The new position in the stream.</returns>
 		/// <exception cref="NotSupportedException">Any access</exception>
 		public override long Seek(long offset, SeekOrigin origin)
 		{
@@ -146,6 +149,7 @@ public override long Seek(long offset, SeekOrigin origin)
 		/// Sets the length of the stream
 		/// This operation is not supported and will throw a NotSupportedException
 		/// </summary>
+		/// <param name="value">The new stream length.</param>
 		/// <exception cref="NotSupportedException">Any access</exception>
 		public override void SetLength(long value)
 		{
@@ -156,6 +160,9 @@ public override void SetLength(long value)
 		/// Writes a block of bytes to this stream using data from a buffer.
 		/// This operation is not supported and will throw a NotSupportedException
 		/// </summary>
+		/// <param name="buffer">The buffer containing bytes to write.</param>
+		/// <param name="offset">The offset in the buffer of the frist byte to write.</param>
+		/// <param name="count">The number of bytes to write.</param>
 		/// <exception cref="NotSupportedException">Any access</exception>
 		public override void Write(byte[] buffer, int offset, int count)
 		{
@@ -166,15 +173,16 @@ public override void Write(byte[] buffer, int offset, int count)
 		/// Writes a byte to the current position in the file stream.
 		/// This operation is not supported and will throw a NotSupportedException
 		/// </summary>
+		/// <param name="value">The byte value to write.</param>
 		/// <exception cref="NotSupportedException">Any access</exception>
 		public override void WriteByte(byte value)
 		{
 			throw new NotSupportedException("TarInputStream WriteByte not supported");
 		}
 		/// <summary>
 		/// Reads a byte from the current tar archive entry.
-		/// This method simply calls Read(byte[], int, int).
 		/// </summary>
+		/// <returns>A byte cast to an int; -1 if the at the end of the stream.</returns>
 		public override int ReadByte()
 		{
 			byte[] oneByteBuffer = new byte[1];
@@ -473,8 +481,8 @@ public TarEntry GetNextEntry()
 						SkipToNextEntry();
 						headerBuf = this.buffer.ReadBlock();
 					} else if (header.TypeFlag != TarHeader.LF_NORMAL && 
-					           header.TypeFlag != TarHeader.LF_OLDNORM &&
-					           header.TypeFlag != TarHeader.LF_DIR) {
+							   header.TypeFlag != TarHeader.LF_OLDNORM &&
+							   header.TypeFlag != TarHeader.LF_DIR) {
 						// Ignore things we dont understand completely for now
 						SkipToNextEntry();
 						headerBuf = this.buffer.ReadBlock();
@@ -588,6 +596,7 @@ public class EntryFactoryAdapter : IEntryFactory
 			/// Create a <see cref="TarEntry"/> based on named
 			/// </summary>
 			/// <param name="name">The name to use for the entry</param>
+			/// <returns>A new <see cref="TarEntry"/></returns>
 			public TarEntry CreateEntry(string name)
 			{
 				return TarEntry.CreateTarEntry(name);
@@ -597,6 +606,7 @@ public TarEntry CreateEntry(string name)
 			/// Create a tar entry with details obtained from <paramref name="fileName">file</paramref>
 			/// </summary>
 			/// <param name="fileName">The name of the file to retrieve details from.</param>
+			/// <returns>A new <see cref="TarEntry"/></returns>
 			public TarEntry CreateEntryFromFile(string fileName)
 			{
 				return TarEntry.CreateEntryFromFile(fileName);
@@ -606,13 +616,13 @@ public TarEntry CreateEntryFromFile(string fileName)
 			/// Create an entry based on details in <paramref name="headerBuf">header</paramref>
 			/// </summary>			
 			/// <param name="headerBuffer">The buffer containing entry details.</param>
+			/// <returns>A new <see cref="TarEntry"/></returns>
 			public TarEntry CreateEntry(byte[] headerBuffer)
 			{
 				return new TarEntry(headerBuffer);
 			}
 		}
 
-
 		#region Instance Fields
 		/// <summary>
 		/// Flag set when last block has been read

src/Tar/TarOutputStream.cs

@@ -141,14 +141,18 @@ public override long Position
 		/// <summary>
 		/// set the position within the current stream
 		/// </summary>
+		/// <param name="offset">The offset relative to the <paramref name="origin"/> to seek to</param>
+		/// <param name="origin">The <see cref="SeekOrigin"/> to seek from.</param>
+		/// <returns>The new position in the stream.</returns>
 		public override long Seek(long offset, SeekOrigin origin)
 		{
 			return outputStream.Seek(offset, origin);
 		}
 
 		/// <summary>
-		/// set the length of the current stream
+		/// Set the length of the current stream
 		/// </summary>
+		/// <param name="value">The new stream length.</param>
 		public override void SetLength(long value)
 		{
 			outputStream.SetLength(value);
@@ -168,7 +172,12 @@ public override int ReadByte()
 		/// read bytes from the current stream and advance the position within the 
 		/// stream by the number of bytes read.
 		/// </summary>
-		/// <returns>The total number of bytes read, or zero if at the end of the stream</returns>
+		/// <param name="buffer">The buffer to store read bytes in.</param>
+		/// <param name="offset">The index into the buffer to being storing bytes at.</param>
+		/// <param name="count">The desired number of bytes to read.</param>
+		/// <returns>The total number of bytes read, or zero if at the end of the stream.
+		/// The number of bytes may be less than the <paramref name="count">count</paramref>
+		/// requested if data is not avialable.</returns>
 		public override int Read(byte[] buffer, int offset, int count)
 		{
 			return outputStream.Read(buffer, offset, count);
@@ -313,7 +322,7 @@ public void CloseEntry()
 			if (currBytes < currSize) {
 				string errorText = string.Format(
 					"Entry closed at '{0}' before the '{1}' bytes specified in the header were written",
-                    currBytes, currSize);
+					currBytes, currSize);
 				throw new TarException(errorText);
 			}
 		}