archive/zip: use proper doc comment for Deprecated notes

End-of-line comments are not doc comments,
so Deprecated notes in them are not recognized
as deprecation notices. Rewrite the comments.

Change-Id: Idc4681924f9a7e9ead62f672ef8a763e70db1f0f
Reviewed-on: https://go-review.googlesource.com/c/go/+/453616
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Joseph Tsai <joetsai@digital-static.net>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: Russ Cox <rsc@golang.org>
Auto-Submit: Russ Cox <rsc@golang.org>

1 files changed, 43 insertions, 13 deletions

diff --git a/src/archive/zip/struct.go b/src/archive/zip/struct.go
index 08af88b245..9c37084778 100644
--- a/src/archive/zip/struct.go
+++ b/src/archive/zip/struct.go
@@ -5,7 +5,7 @@
 /*
 Package zip provides support for reading and writing ZIP archives.
 
-See: https://www.pkware.com/appnote
+See the [ZIP specification] for details.
 
 This package does not support disk spanning.
 
@@ -16,6 +16,8 @@ fields. The 64 bit fields will always contain the correct value and
 for normal archives both fields will be the same. For files requiring
 the ZIP64 format the 32 bit fields will be 0xffffffff and the 64 bit
 fields must be used instead.
+
+[ZIP specification]: https://www.pkware.com/appnote
 */
 package zip
 
@@ -77,8 +79,10 @@ const (
 	infoZipUnixExtraID = 0x5855 // Info-ZIP Unix extension
 )
 
-// FileHeader describes a file within a zip file.
-// See the zip spec for details.
+// FileHeader describes a file within a ZIP file.
+// See the [ZIP specification] for details.
+//
+// [ZIP specification]: https://www.pkware.com/appnote
 type FileHeader struct {
 	// Name is the name of the file.
 	//
@@ -117,17 +121,43 @@ type FileHeader struct {
 	// When writing, an extended timestamp (which is timezone-agnostic) is
 	// always emitted. The legacy MS-DOS date field is encoded according to the
 	// location of the Modified time.
-	Modified     time.Time
-	ModifiedTime uint16 // Deprecated: Legacy MS-DOS date; use Modified instead.
-	ModifiedDate uint16 // Deprecated: Legacy MS-DOS time; use Modified instead.
-
-	CRC32              uint32
-	CompressedSize     uint32 // Deprecated: Use CompressedSize64 instead.
-	UncompressedSize   uint32 // Deprecated: Use UncompressedSize64 instead.
-	CompressedSize64   uint64
+	Modified time.Time
+
+	// ModifiedTime is an MS-DOS-encoded time.
+	//
+	// Deprecated: Use Modified instead.
+	ModifiedTime uint16
+
+	// ModifiedDate is an MS-DOS-encoded date.
+	//
+	// Deprecated: Use Modified instead.
+	ModifiedDate uint16
+
+	// CRC32 is the CRC32 checksum of the file content.
+	CRC32 uint32
+
+	// CompressedSize is the compressed size of the file in bytes.
+	// If either the uncompressed or compressed size of the file
+	// does not fit in 32 bits, CompressedSize is set to ^uint32(0).
+	//
+	// Deprecated: Use CompressedSize64 instead.
+	CompressedSize uint32
+
+	// UncompressedSize is the compressed size of the file in bytes.
+	// If either the uncompressed or compressed size of the file
+	// does not fit in 32 bits, CompressedSize is set to ^uint32(0).
+	//
+	// Deprecated: Use UncompressedSize64 instead.
+	UncompressedSize uint32
+
+	// CompressedSize64 is the compressed size of the file in bytes.
+	CompressedSize64 uint64
+
+	// UncompressedSize64 is the uncompressed size of the file in bytes.
 	UncompressedSize64 uint64
-	Extra              []byte
-	ExternalAttrs      uint32 // Meaning depends on CreatorVersion
+
+	Extra         []byte
+	ExternalAttrs uint32 // Meaning depends on CreatorVersion
 }
 
 // FileInfo returns an fs.FileInfo for the FileHeader.