Documentation updates for Zip64 and unicode.

Author: jfreilly

src/AssemblyInfo.cs

@@ -73,8 +73,8 @@
 [assembly: AssemblyCopyright("Copyright 2001-2007 Mike Krueger, John Reilly")]
 [assembly: AssemblyTrademark("Copyright 2001-2007 Mike Krueger, John Reilly")]
 
-[assembly: AssemblyVersion("0.85.3.365")]
-[assembly: AssemblyInformationalVersionAttribute("0.85.3")]
+[assembly: AssemblyVersion("0.85.4.365")]
+[assembly: AssemblyInformationalVersionAttribute("0.85.4")]
 
 
 [assembly: CLSCompliant(true)]

src/Zip/ZipEntry.cs

@@ -286,6 +286,7 @@ public bool HasCrc
 		/// Get/Set flag indicating if entry is encrypted.
 		/// A simple helper routine to aid interpretation of <see cref="Flags">flags</see>
 		/// </summary>
+		/// <remarks>This is an assistant that interprets the <see cref="Flags">flags</see> property.</remarks>
 		public bool IsCrypted 
 		{
 			get {
@@ -303,8 +304,9 @@ public bool IsCrypted
 
 		/// <summary>
 		/// Get / set a flag indicating wether entry name and comment text are
-		/// encoded in Unicode UTF8
+		/// encoded in <a href="http://www.unicode.org">unicode UTF8</a>.
 		/// </summary>
+		/// <remarks>This is an assistant that interprets the <see cref="Flags">flags</see> property.</remarks>
 		public bool IsUnicodeText
 		{
 			get {
@@ -339,6 +341,7 @@ internal byte CryptoCheckValue
 		/// </summary>
 		/// <remarks>
 		/// General purpose bit flag<br/>
+		/// <br/>
 		/// Bit 0: If set, indicates the file is encrypted<br/>
 		/// Bit 1-2 Only used for compression type 6 Imploding, and 8, 9 deflating<br/>
 		/// Imploding:<br/>
@@ -358,8 +361,12 @@ internal byte CryptoCheckValue
 		/// Bit 4: Reserved for use by PKZIP for enhanced deflating<br/>
 		/// Bit 5: If set indicates the file contains compressed patch data<br/>
 		/// Bit 6: If set indicates strong encryption was used.<br/>
-		/// Bit 7-15: Unused or reserved<br/>
+		/// Bit 7-10: Unused or reserved<br/>
+		/// Bit 11: If set the name and comments for this entry are in <a href="http://www.unicode.org">unicode</a>.<br/>
+		/// Bit 12-15: Unused or reserved<br/>
 		/// </remarks>
+		/// <seealso cref="IsUnicodeText"></seealso>
+		/// <seealso cref="IsCrypted"></seealso>
 		public int Flags 
 		{
 			get { 
@@ -373,6 +380,7 @@ public int Flags
 		/// <summary>
 		/// Get/Set index of this entry in Zip file
 		/// </summary>
+		/// <remarks>This is only valid when the entry is part of a <see cref="ZipFile"></see></remarks>
 		public long ZipFileIndex 
 		{
 			get {
@@ -741,6 +749,8 @@ public string Name
 		/// <returns>
 		/// The size or -1 if unknown.
 		/// </returns>
+		/// <remarks>Setting the size before adding an entry to an archive can help
+		/// avoid compatability problems with some archivers which dont understand Zip64 extensions.</remarks>
 		public long Size 
 		{
 			get {

src/Zip/ZipOutputStream.cs

@@ -121,13 +121,14 @@ public bool IsFinished
 		/// Set the zip file comment.
 		/// </summary>
 		/// <param name="comment">
-		/// The comment string
+		/// The comment text for the entire archive.
 		/// </param>
 		/// <exception name ="ArgumentOutOfRangeException">
-		/// Encoding of comment is longer than 0xffff bytes.
+		/// The <see cref="ZipConstants.DefaultCodePage">encoded</see> comment is longer than 0xffff bytes.
 		/// </exception>
 		public void SetComment(string comment)
 		{
+			// TODO: Its not yet clear how to handle unicode comments here.
 			byte[] commentBytes = ZipConstants.ConvertToArray(comment);
 			if (commentBytes.Length > 0xffff) {
 				throw new ArgumentOutOfRangeException("comment");
@@ -161,6 +162,10 @@ public int GetLevel()
 		/// <summary>
 		/// Get / set a value indicating how Zip64 Extension usage is determined when adding entries.
 		/// </summary>
+		/// <remarks>Older archivers may not understand Zip64 extensions.
+		/// If backwards compatability is an issue be careful when adding <see cref="ZipEntry.Size">entries</see> to an archive.
+		/// Setting this property to off is workable but less desirable as in those circumstances adding a file
+		/// larger then 4GB will fail.</remarks>
 		public UseZip64 UseZip64
 		{
 			get { return useZip64_; }
@@ -804,6 +809,7 @@ public override void Finish()
 		// Default is dynamic which is not backwards compatible and can cause problems
 		// with XP's built in compression which cant read Zip64 archives.
 		// However it does avoid the situation were a large file is added and cannot be completed correctly.
+		// NOTE: Setting the size for entries before they are added is the best solution!
 		UseZip64 useZip64_ = UseZip64.Dynamic;
 		#endregion
 	}

tests/AssemblyInfo.cs

@@ -23,7 +23,7 @@
 // You can specify all values by your own or you can build default build and revision
 // numbers with the '*' character (the default):
 
-[assembly: AssemblyVersion("0.85.3.365")]
+[assembly: AssemblyVersion("0.85.4.365")]
 
 // The following attributes specify the key for the sign of your assembly. See the
 // .NET Framework documentation for more information about signing.