basic jsdoc pass for ZipArchiveEntry.

Author: ctalkington

lib/archivers/zip/zip-archive-entry.js

@@ -46,78 +46,173 @@ var ZipArchiveEntry = module.exports = function(name) {
 
 inherits(ZipArchiveEntry, ArchiveEntry);
 
+/**
+ * Returns the extra fields related to the entry.
+ *
+ * @returns {Buffer}
+ */
 ZipArchiveEntry.prototype.getCentralDirectoryExtra = function() {
   return this.getExtra();
 };
 
+/**
+ * Returns the comment set for the entry.
+ *
+ * @returns {string}
+ */
 ZipArchiveEntry.prototype.getComment = function() {
   return this.comment !== null ? this.comment : '';
 };
 
+/**
+ * Returns the compressed size of the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getCompressedSize = function() {
   return this.csize;
 };
 
+/**
+ * Returns the CRC32 digest for the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getCrc = function() {
   return this.crc;
 };
 
+/**
+ * Returns the external file attributes for the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getExternalAttributes = function() {
   return this.exattr;
 };
 
+/**
+ * Returns the extra fields related to the entry.
+ *
+ * @returns {Buffer}
+ */
 ZipArchiveEntry.prototype.getExtra = function() {
   return this.extra !== null ? this.extra : constants.EMPTY;
 };
 
+/**
+ * Returns the general purpose bits related to the entry.
+ *
+ * @returns {GeneralPurposeBit}
+ */
 ZipArchiveEntry.prototype.getGeneralPurposeBit = function() {
   return this.gpb;
 };
 
+/**
+ * Returns the internal file attributes for the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getInternalAttributes = function() {
   return this.inattr;
 };
 
+/**
+ * Returns the last modified date of the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getLastModifiedDate = function() {
   return this.getTime();
 };
 
+/**
+ * Returns the extra fields related to the entry.
+ *
+ * @returns {Buffer}
+ */
 ZipArchiveEntry.prototype.getLocalFileDataExtra = function() {
   return this.getExtra();
 };
 
+/**
+ * Returns the compression method used on the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getMethod = function() {
   return this.method;
 };
 
+/**
+ * Returns the filename of the entry.
+ *
+ * @returns {string}
+ */
 ZipArchiveEntry.prototype.getName = function() {
   return this.name;
 };
 
+/**
+ * Returns the platform on which the entry was made.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getPlatform = function() {
   return this.platform;
 };
 
+/**
+ * Returns the size of the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getSize = function() {
   return this.size;
 };
 
+/**
+ * Returns a date object representing the last modified date of the entry.
+ *
+ * @returns {number|Date}
+ */
 ZipArchiveEntry.prototype.getTime = function() {
   return this.time !== -1 ? zipUtil.dosToDate(this.time) : -1;
 };
 
+/**
+ * Returns the DOS timestamp for the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getTimeDos = function() {
   return this.time !== -1 ? this.time : 0;
 };
 
+/**
+ * Returns the UNIX file permissions for the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getUnixMode = function() {
   return this.platform !== constants.PLATFORM_UNIX ? 0 : ((this.getExternalAttributes() >> constants.SHORT_SHIFT) & constants.SHORT_MASK);
 };
 
+/**
+ * Returns the version of ZIP needed to extract the entry.
+ *
+ * @returns {number}
+ */
 ZipArchiveEntry.prototype.getVersionNeededToExtract = function() {
   return this.minver;
 };
 
+/**
+ * Sets the comment of the entry.
+ *
+ * @param comment
+ */
 ZipArchiveEntry.prototype.setComment = function(comment) {
   if (Buffer.byteLength(comment) !== comment.length) {
     this.getGeneralPurposeBit().useUTF8ForNames(true);
@@ -126,6 +221,11 @@ ZipArchiveEntry.prototype.setComment = function(comment) {
   this.comment = comment;
 };
 
+/**
+ * Sets the compressed size of the entry.
+ *
+ * @param size
+ */
 ZipArchiveEntry.prototype.setCompressedSize = function(size) {
   if (size < 0) {
     throw new Error('invalid entry compressed size');
@@ -134,6 +234,11 @@ ZipArchiveEntry.prototype.setCompressedSize = function(size) {
   this.csize = size;
 };
 
+/**
+ * Sets the checksum of the entry.
+ *
+ * @param crc
+ */
 ZipArchiveEntry.prototype.setCrc = function(crc) {
   if (crc < 0) {
     throw new Error('invalid entry crc32');
@@ -142,14 +247,29 @@ ZipArchiveEntry.prototype.setCrc = function(crc) {
   this.crc = crc;
 };
 
+/**
+ * Sets the external file attributes of the entry.
+ *
+ * @param attr
+ */
 ZipArchiveEntry.prototype.setExternalAttributes = function(attr) {
   this.exattr = attr >>> 0;
 };
 
+/**
+ * Sets the extra fields related to the entry.
+ *
+ * @param extra
+ */
 ZipArchiveEntry.prototype.setExtra = function(extra) {
   this.extra = extra;
 };
 
+/**
+ * Sets the general purpose bits related to the entry.
+ *
+ * @param gpb
+ */
 ZipArchiveEntry.prototype.setGeneralPurposeBit = function(gpb) {
   if (!(gpb instanceof GeneralPurposeBit)) {
     throw new Error('invalid entry GeneralPurposeBit');
@@ -158,10 +278,20 @@ ZipArchiveEntry.prototype.setGeneralPurposeBit = function(gpb) {
   this.gpb = gpb;
 };
 
+/**
+ * Sets the internal file attributes of the entry.
+ *
+ * @param attr
+ */
 ZipArchiveEntry.prototype.setInternalAttributes = function(attr) {
   this.inattr = attr;
 };
 
+/**
+ * Sets the compression method of the entry.
+ *
+ * @param method
+ */
 ZipArchiveEntry.prototype.setMethod = function(method) {
   if (method < 0) {
     throw new Error('invalid entry compression method');
@@ -170,6 +300,11 @@ ZipArchiveEntry.prototype.setMethod = function(method) {
   this.method = method;
 };
 
+/**
+ * Sets the name of the entry.
+ *
+ * @param name
+ */
 ZipArchiveEntry.prototype.setName = function(name) {
   name = normalizePath(name, false).replace(/^\w+:/, '').replace(/^(\.\.\/|\/)+/, '');
 
@@ -180,10 +315,20 @@ ZipArchiveEntry.prototype.setName = function(name) {
   this.name = name;
 };
 
+/**
+ * Sets the platform on which the entry was made.
+ *
+ * @param platform
+ */
 ZipArchiveEntry.prototype.setPlatform = function(platform) {
   this.platform = platform;
 };
 
+/**
+ * Sets the size of the entry.
+ *
+ * @param size
+ */
 ZipArchiveEntry.prototype.setSize = function(size) {
   if (size < 0) {
     throw new Error('invalid entry size');
@@ -192,6 +337,12 @@ ZipArchiveEntry.prototype.setSize = function(size) {
   this.size = size;
 };
 
+/**
+ * Sets the time of the entry.
+ *
+ * @param time
+ * @param forceLocalTime
+ */
 ZipArchiveEntry.prototype.setTime = function(time, forceLocalTime) {
   if (!(time instanceof Date)) {
     throw new Error('invalid entry time');
@@ -200,6 +351,11 @@ ZipArchiveEntry.prototype.setTime = function(time, forceLocalTime) {
   this.time = zipUtil.dateToDos(time, forceLocalTime);
 };
 
+/**
+ * Sets the UNIX file permissions for the entry.
+ *
+ * @param mode
+ */
 ZipArchiveEntry.prototype.setUnixMode = function(mode) {
   mode |= this.isDirectory() ? constants.S_IFDIR : constants.S_IFREG;
 
@@ -211,18 +367,40 @@ ZipArchiveEntry.prototype.setUnixMode = function(mode) {
   this.platform = constants.PLATFORM_UNIX;
 };
 
+/**
+ * Sets the version of ZIP needed to extract this entry.
+ *
+ * @param minver
+ */
 ZipArchiveEntry.prototype.setVersionNeededToExtract = function(minver) {
   this.minver = minver;
 };
 
+/**
+ * Returns true if this entry represents a directory.
+ *
+ * @returns {boolean}
+ */
 ZipArchiveEntry.prototype.isDirectory = function() {
   return this.getName().slice(-1) === '/';
 };
 
+/**
+ * Returns true if this entry represents a unix symlink,
+ * in which case the entry's content contains the target path
+ * for the symlink.
+ *
+ * @returns {boolean}
+ */
 ZipArchiveEntry.prototype.isUnixSymlink = function() {
   return (this.getUnixMode() & UnixStat.FILE_TYPE_FLAG) === UnixStat.LINK_FLAG;
 };
 
+/**
+ * Returns true if this entry is using the ZIP64 extension of ZIP.
+ *
+ * @returns {boolean}
+ */
 ZipArchiveEntry.prototype.isZip64 = function() {
   return this.csize > constants.ZIP64_MAGIC || this.size > constants.ZIP64_MAGIC;
 };