From 4ded3f9d58714572b2e17d11040a09c88b7331be Mon Sep 17 00:00:00 2001
From: Mahrud Sayrafi <mahrud@berkeley.edu>
Date: Fri, 9 Mar 2018 01:41:15 -0800
Subject: [PATCH] Documentation improvements in src/packet

---
 src/packet/all_packets.js                     |   8 +-
 src/packet/clone.js                           |  14 +-
 src/packet/compressed.js                      | 136 +++++++++---------
 src/packet/index.js                           |  12 +-
 src/packet/literal.js                         |  18 +--
 src/packet/marker.js                          |  14 +-
 src/packet/one_pass_signature.js              |  60 +++++---
 src/packet/packet.js                          |   2 +-
 src/packet/packetlist.js                      |  67 ++++-----
 src/packet/public_key.js                      |  10 +-
 .../public_key_encrypted_session_key.js       |  34 ++---
 src/packet/public_subkey.js                   |   8 +-
 src/packet/secret_key.js                      |  19 +--
 src/packet/secret_subkey.js                   |   8 +-
 src/packet/signature.js                       |  44 +++---
 src/packet/sym_encrypted_aead_protected.js    |  12 +-
 .../sym_encrypted_integrity_protected.js      |  18 +--
 src/packet/sym_encrypted_session_key.js       |  26 ++--
 src/packet/symmetrically_encrypted.js         |  21 +--
 src/packet/trust.js                           |  14 +-
 src/packet/user_attribute.js                  |  21 +--
 src/packet/userid.js                          |  18 +--
 22 files changed, 313 insertions(+), 271 deletions(-)

diff --git a/src/packet/all_packets.js b/src/packet/all_packets.js
index f54b0e67..a4c15211 100644
--- a/src/packet/all_packets.js
+++ b/src/packet/all_packets.js
@@ -1,6 +1,5 @@
 /**
  * @requires enums
- * @module packet/all_packets
  */
 
 import enums from '../enums.js';
@@ -43,6 +42,8 @@ export { default as Trust } from './trust.js';
 
 /**
  * Allocate a new packet
+ * @function newPacketFromTag
+ * @memberof module:packet
  * @param {String} tag property name from {@link module:enums.packet}
  * @returns {Object} new packet object with type based on tag
  */
@@ -52,7 +53,9 @@ export function newPacketFromTag(tag) {
 
 /**
  * Allocate a new packet from structured packet clone
- * See {@link https://w3c.github.io/html/infrastructure.html#safe-passing-of-structured-data}
+ * @see {@link https://w3c.github.io/html/infrastructure.html#safe-passing-of-structured-data}
+ * @function fromStructuredClone
+ * @memberof module:packet
  * @param {Object} packetClone packet clone
  * @returns {Object} new packet object with data from packet clone
  */
@@ -74,6 +77,7 @@ export function fromStructuredClone(packetClone) {
  * Convert tag name to class name
  * @param {String} tag property name from {@link module:enums.packet}
  * @returns {String}
+ * @private
  */
 function packetClassFromTagName(tag) {
   return tag.substr(0, 1).toUpperCase() + tag.substr(1);
diff --git a/src/packet/clone.js b/src/packet/clone.js
index 227f67aa..e5d5b048 100644
--- a/src/packet/clone.js
+++ b/src/packet/clone.js
@@ -26,14 +26,14 @@ import { Key } from '../key';
 import { Message } from '../message';
 import { CleartextMessage } from '../cleartext';
 import { Signature } from '../signature';
-import Packetlist from './packetlist';
+import List from './packetlist';
 import type_keyid from '../type/keyid';
 import util from '../util';
 
 
 //////////////////////////////
 //                          //
-//   Packetlist --> Clone   //
+//   List --> Clone   //
 //                          //
 //////////////////////////////
 
@@ -80,7 +80,7 @@ function verificationObjectToClone(verObject) {
 
 //////////////////////////////
 //                          //
-//   Clone --> Packetlist   //
+//   Clone --> List   //
 //                          //
 //////////////////////////////
 
@@ -119,17 +119,17 @@ export function parseClonedPackets(options) {
 }
 
 function packetlistCloneToKey(clone) {
-  const packetlist = Packetlist.fromStructuredClone(clone);
+  const packetlist = List.fromStructuredClone(clone);
   return new Key(packetlist);
 }
 
 function packetlistCloneToMessage(clone) {
-  const packetlist = Packetlist.fromStructuredClone(clone);
+  const packetlist = List.fromStructuredClone(clone);
   return new Message(packetlist);
 }
 
 function packetlistCloneToCleartextMessage(clone) {
-  const packetlist = Packetlist.fromStructuredClone(clone.signature);
+  const packetlist = List.fromStructuredClone(clone.signature);
   return new CleartextMessage(clone.text, new Signature(packetlist));
 }
 
@@ -145,6 +145,6 @@ function packetlistCloneToSignature(clone) {
     //signature is armored
     return clone;
   }
-  const packetlist = Packetlist.fromStructuredClone(clone);
+  const packetlist = List.fromStructuredClone(clone);
   return new Signature(packetlist);
 }
diff --git a/src/packet/compressed.js b/src/packet/compressed.js
index a06e5541..c46de4a5 100644
--- a/src/packet/compressed.js
+++ b/src/packet/compressed.js
@@ -15,6 +15,20 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires pako
+ * @requires config
+ * @requires enums
+ * @requires util
+ * @requires compression/bzip2
+ */
+
+import pako from 'pako';
+import config from '../config';
+import enums from '../enums';
+import util from '../util';
+import Bzip2 from '../compression/bzip2.build.js';
+
 /**
  * Implementation of the Compressed Data Packet (Tag 8)
  *
@@ -22,71 +36,7 @@
  * The Compressed Data packet contains compressed data.  Typically,
  * this packet is found as the contents of an encrypted packet, or following
  * a Signature or One-Pass Signature packet, and contains a literal data packet.
- * @requires compression/zlib
- * @requires compression/rawinflate
- * @requires compression/rawdeflate
- * @requires compression/bzip2
- * @requires enums
- * @requires util
- * @module packet/compressed
- */
-
-import pako from 'pako';
-import config from '../config';
-import enums from '../enums.js';
-import util from '../util.js';
-import Bzip2 from '../compression/bzip2.build.js';
-
-const nodeZlib = util.getNodeZlib();
-const Buffer = util.getNodeBuffer();
-
-function node_zlib(func, options = {}) {
-  return function (data) {
-    return func(data, options);
-  };
-}
-
-function pako_zlib(constructor, options = {}) {
-  return function(data) {
-      const obj = new constructor(options);
-      obj.push(data, true);
-      return obj.result;
-  };
-}
-
-let compress_fns;
-let decompress_fns;
-if (nodeZlib) { // Use Node native zlib for DEFLATE compression/decompression
-  compress_fns = {
-    // eslint-disable-next-line no-sync
-    zip: node_zlib(nodeZlib.deflateRawSync, { level: config.deflate_level }),
-    // eslint-disable-next-line no-sync
-    zlib: node_zlib(nodeZlib.deflateSync, { level: config.deflate_level }),
-    bzip2: Bzip2.compressFile
-  };
-
-  decompress_fns = {
-    // eslint-disable-next-line no-sync
-    zip: node_zlib(nodeZlib.inflateRawSync),
-    // eslint-disable-next-line no-sync
-    zlib: node_zlib(nodeZlib.inflateSync),
-    bzip2: Bzip2.decompressFile
-  };
-} else { // Use JS fallbacks
-  compress_fns = {
-    zip: pako_zlib(pako.Deflate, { raw: true, level: config.deflate_level }),
-    zlib: pako_zlib(pako.Deflate, { level: config.deflate_level }),
-    bzip2: Bzip2.compressFile
-  };
-
-  decompress_fns = {
-    zip: pako_zlib(pako.Inflate, { raw: true }),
-    zlib: pako_zlib(pako.Inflate),
-    bzip2: Bzip2.decompressFile
-  };
-}
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function Compressed() {
@@ -167,3 +117,59 @@ Compressed.prototype.compress = function () {
 };
 
 export default Compressed;
+
+//////////////////////////
+//                      //
+//   Helper functions   //
+//                      //
+//////////////////////////
+
+
+const nodeZlib = util.getNodeZlib();
+const Buffer = util.getNodeBuffer();
+
+function node_zlib(func, options = {}) {
+  return function (data) {
+    return func(data, options);
+  };
+}
+
+function pako_zlib(constructor, options = {}) {
+  return function(data) {
+      const obj = new constructor(options);
+      obj.push(data, true);
+      return obj.result;
+  };
+}
+
+let compress_fns;
+let decompress_fns;
+if (nodeZlib) { // Use Node native zlib for DEFLATE compression/decompression
+  compress_fns = {
+    // eslint-disable-next-line no-sync
+    zip: node_zlib(nodeZlib.deflateRawSync, { level: config.deflate_level }),
+    // eslint-disable-next-line no-sync
+    zlib: node_zlib(nodeZlib.deflateSync, { level: config.deflate_level }),
+    bzip2: Bzip2.compressFile
+  };
+
+  decompress_fns = {
+    // eslint-disable-next-line no-sync
+    zip: node_zlib(nodeZlib.inflateRawSync),
+    // eslint-disable-next-line no-sync
+    zlib: node_zlib(nodeZlib.inflateSync),
+    bzip2: Bzip2.decompressFile
+  };
+} else { // Use JS fallbacks
+  compress_fns = {
+    zip: pako_zlib(pako.Deflate, { raw: true, level: config.deflate_level }),
+    zlib: pako_zlib(pako.Deflate, { level: config.deflate_level }),
+    bzip2: Bzip2.compressFile
+  };
+
+  decompress_fns = {
+    zip: pako_zlib(pako.Inflate, { raw: true }),
+    zlib: pako_zlib(pako.Inflate),
+    bzip2: Bzip2.decompressFile
+  };
+}
diff --git a/src/packet/index.js b/src/packet/index.js
index 0f372eea..8c1b30c9 100644
--- a/src/packet/index.js
+++ b/src/packet/index.js
@@ -6,15 +6,13 @@
  * @module packet
  */
 
-import * as packets from './all_packets.js';
-import * as clone from './clone.js';
-import List from './packetlist.js';
+import * as packets from './all_packets';
+import * as clone from './clone';
+import List from './packetlist';
 
 const mod = {
-  /** @see module:packet/packetlist */
-  List: List,
-  /** @see module:packet/clone */
-  clone: clone
+  List,
+  clone
 };
 
 for (const i in packets) {
diff --git a/src/packet/literal.js b/src/packet/literal.js
index a3e85315..6f90cfd5 100644
--- a/src/packet/literal.js
+++ b/src/packet/literal.js
@@ -15,22 +15,22 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires enums
+ * @requires util
+ */
+
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Implementation of the Literal Data Packet (Tag 11)
  *
  * {@link https://tools.ietf.org/html/rfc4880#section-5.9|RFC4880 5.9}:
  * A Literal Data packet contains the body of a message; data that is not to be
  * further interpreted.
- * @requires enums
- * @requires util
- * @module packet/literal
- */
-
-import util from '../util.js';
-import enums from '../enums.js';
-
-/**
  * @param {Date} date the creation date of the literal package
+ * @memberof module:packet
  * @constructor
  */
 function Literal(date=new Date()) {
diff --git a/src/packet/marker.js b/src/packet/marker.js
index 2cafd114..525b13f7 100644
--- a/src/packet/marker.js
+++ b/src/packet/marker.js
@@ -15,6 +15,12 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires enums
+ */
+
+import enums from '../enums';
+
 /**
  * Implementation of the strange "Marker packet" (Tag 10)
  *
@@ -25,13 +31,7 @@
  * the Marker packet.
  *
  * Such a packet MUST be ignored when received.
- * @requires enums
- * @module packet/marker
- */
-
-import enums from '../enums.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function Marker() {
diff --git a/src/packet/one_pass_signature.js b/src/packet/one_pass_signature.js
index 96261850..c29b9f16 100644
--- a/src/packet/one_pass_signature.js
+++ b/src/packet/one_pass_signature.js
@@ -15,6 +15,16 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires type/keyid
+ * @requires enums
+ * @requires util
+*/
+
+import type_keyid from '../type/keyid';
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Implementation of the One-Pass Signature Packets (Tag 4)
  *
@@ -24,27 +34,41 @@
  * hashes needed to verify the signature.  It allows the Signature
  * packet to be placed at the end of the message, so that the signer
  * can compute the entire signed message in one pass.
- * @requires util
- * @requires enums
- * @requires type/keyid
- * @module packet/one_pass_signature
-*/
-
-import util from '../util.js';
-import enums from '../enums.js';
-import type_keyid from '../type/keyid.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function OnePassSignature() {
-  this.tag = enums.packet.onePassSignature; // The packet type
-  this.version = null; // A one-octet version number.  The current version is 3.
-  this.type = null; // A one-octet signature type.  Signature types are described in {@link https://tools.ietf.org/html/rfc4880#section-5.2.1|RFC4880 Section 5.2.1}.
-  this.hashAlgorithm = null; // A one-octet number describing the hash algorithm used. (See {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC4880 9.4})
-  this.publicKeyAlgorithm = null; // A one-octet number describing the public-key algorithm used. (See {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC4880 9.1})
-  this.signingKeyId = null; // An eight-octet number holding the Key ID of the signing key.
-  this.flags = null; //  A one-octet number holding a flag showing whether the signature is nested.  A zero value indicates that the next packet is another One-Pass Signature packet that describes another signature to be applied to the same message data.
+  /**
+   * Packet type
+   * @type {module:enums.packet}
+   */
+  this.tag = enums.packet.onePassSignature;
+  /** A one-octet version number.  The current version is 3. */
+  this.version = null;
+  /**
+   * A one-octet signature type.
+   * Signature types are described in
+   * {@link https://tools.ietf.org/html/rfc4880#section-5.2.1|RFC4880 Section 5.2.1}.
+   */
+  this.type = null;
+  /**
+   * A one-octet number describing the hash algorithm used.
+   * @see {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC4880 9.4}
+   */
+  this.hashAlgorithm = null;
+  /**
+   * A one-octet number describing the public-key algorithm used.
+   * @see {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC4880 9.1}
+   */
+  this.publicKeyAlgorithm = null;
+  /** An eight-octet number holding the Key ID of the signing key. */
+  this.signingKeyId = null;
+   /**
+    * A one-octet number holding a flag showing whether the signature is nested.
+    * A zero value indicates that the next packet is another One-Pass Signature packet
+    * that describes another signature to be applied to the same message data.
+    */
+  this.flags = null;
 }
 
 /**
diff --git a/src/packet/packet.js b/src/packet/packet.js
index f3290796..0be5a759 100644
--- a/src/packet/packet.js
+++ b/src/packet/packet.js
@@ -22,7 +22,7 @@
  * @module packet/packet
  */
 
-import util from '../util.js';
+import util from '../util';
 
 export default {
   readSimpleLength: function(bytes) {
diff --git a/src/packet/packetlist.js b/src/packet/packetlist.js
index d2d34761..b41dbd8c 100644
--- a/src/packet/packetlist.js
+++ b/src/packet/packetlist.js
@@ -1,30 +1,32 @@
 /* eslint-disable callback-return */
 /**
  * @fileoverview Provides a class for representing lists of OpenPGP packets.
- * @requires util
- * @requires enums
- * @requires packet
+ * @requires packet/all_packets
  * @requires packet/packet
- * @module packet/packetlist
+ * @requires config
+ * @requires enums
+ * @requires util
  */
 
-import util from '../util';
-import packetParser from './packet.js';
-import * as packets from './all_packets.js';
-import enums from '../enums.js';
+import * as packets from './all_packets';
+import packetParser from './packet';
 import config from '../config';
+import enums from '../enums';
+import util from '../util';
 
 /**
  * This class represents a list of openpgp packets.
  * Take care when iterating over it - the packets themselves
  * are stored as numerical indices.
+ * @memberof module:packet
  * @constructor
  */
-function Packetlist() {
+function List() {
   /**
    * The number of packets contained within the list.
    * @readonly
-   * @type {Integer} */
+   * @type {Integer}
+   */
   this.length = 0;
 }
 
@@ -32,7 +34,7 @@ function Packetlist() {
  * Reads a stream of binary data and interprents it as a list of packets.
  * @param {Uint8Array} A Uint8Array of bytes.
  */
-Packetlist.prototype.read = function (bytes) {
+List.prototype.read = function (bytes) {
   let i = 0;
 
   while (i < bytes.length) {
@@ -65,7 +67,7 @@ Packetlist.prototype.read = function (bytes) {
  * class instance.
  * @returns {Uint8Array} A Uint8Array containing valid openpgp packets.
  */
-Packetlist.prototype.write = function () {
+List.prototype.write = function () {
   const arr = [];
 
   for (let i = 0; i < this.length; i++) {
@@ -80,13 +82,14 @@ Packetlist.prototype.write = function () {
 /**
  * Adds a packet to the list. This is the only supported method of doing so;
  * writing to packetlist[i] directly will result in an error.
+ * @param {Object} packet Packet to push
  */
-Packetlist.prototype.push = function (packet) {
+List.prototype.push = function (packet) {
   if (!packet) {
     return;
   }
 
-  packet.packets = packet.packets || new Packetlist();
+  packet.packets = packet.packets || new List();
 
   this[this.length] = packet;
   this.length++;
@@ -96,7 +99,7 @@ Packetlist.prototype.push = function (packet) {
  * Remove a packet from the list and return it.
  * @returns {Object}   The packet that was removed
  */
-Packetlist.prototype.pop = function() {
+List.prototype.pop = function() {
   if (this.length === 0) {
     return;
   }
@@ -111,8 +114,8 @@ Packetlist.prototype.pop = function() {
 /**
  * Creates a new PacketList with all packets that pass the test implemented by the provided function.
  */
-Packetlist.prototype.filter = function (callback) {
-  const filtered = new Packetlist();
+List.prototype.filter = function (callback) {
+  const filtered = new List();
 
   for (let i = 0; i < this.length; i++) {
     if (callback(this[i], i, this)) {
@@ -126,8 +129,8 @@ Packetlist.prototype.filter = function (callback) {
 /**
  * Creates a new PacketList with all packets from the given types
  */
-Packetlist.prototype.filterByTag = function (...args) {
-  const filtered = new Packetlist();
+List.prototype.filterByTag = function (...args) {
+  const filtered = new List();
   const that = this;
 
   const handle = tag => packetType => tag === packetType;
@@ -144,7 +147,7 @@ Packetlist.prototype.filterByTag = function (...args) {
 /**
  * Executes the provided callback once for each element
  */
-Packetlist.prototype.forEach = function (callback) {
+List.prototype.forEach = function (callback) {
   for (let i = 0; i < this.length; i++) {
     callback(this[i], i, this);
   }
@@ -154,7 +157,7 @@ Packetlist.prototype.forEach = function (callback) {
  * Returns an array containing return values of callback
  * on each element
  */
-Packetlist.prototype.map = function (callback) {
+List.prototype.map = function (callback) {
   const packetArray = [];
 
   for (let i = 0; i < this.length; i++) {
@@ -171,7 +174,7 @@ Packetlist.prototype.map = function (callback) {
  * @returns {Promise<Boolean>}
  * @async
  */
-Packetlist.prototype.some = async function (callback) {
+List.prototype.some = async function (callback) {
   for (let i = 0; i < this.length; i++) {
     // eslint-disable-next-line no-await-in-loop
     if (await callback(this[i], i, this)) {
@@ -185,7 +188,7 @@ Packetlist.prototype.some = async function (callback) {
  * Executes the callback function once for each element,
  * returns true if all callbacks returns a truthy value
  */
-Packetlist.prototype.every = function (callback) {
+List.prototype.every = function (callback) {
   for (let i = 0; i < this.length; i++) {
     if (!callback(this[i], i, this)) {
       return false;
@@ -199,7 +202,7 @@ Packetlist.prototype.every = function (callback) {
  * @param  {module:enums.packet} type The packet type
  * @returns {module:packet/packet|null}
  */
-Packetlist.prototype.findPacket = function (type) {
+List.prototype.findPacket = function (type) {
   const packetlist = this.filterByTag(type);
   if (packetlist.length) {
     return packetlist[0];
@@ -220,7 +223,7 @@ Packetlist.prototype.findPacket = function (type) {
 /**
  * Returns array of found indices by tag
  */
-Packetlist.prototype.indexOfTag = function (...args) {
+List.prototype.indexOfTag = function (...args) {
   const tagIndex = [];
   const that = this;
 
@@ -237,11 +240,11 @@ Packetlist.prototype.indexOfTag = function (...args) {
 /**
  * Returns slice of packetlist
  */
-Packetlist.prototype.slice = function (begin, end) {
+List.prototype.slice = function (begin, end) {
   if (!end) {
     end = this.length;
   }
-  const part = new Packetlist();
+  const part = new List();
   for (let i = begin; i < end; i++) {
     part.push(this[i]);
   }
@@ -251,7 +254,7 @@ Packetlist.prototype.slice = function (begin, end) {
 /**
  * Concatenates packetlist or array of packets
  */
-Packetlist.prototype.concat = function (packetlist) {
+List.prototype.concat = function (packetlist) {
   if (packetlist) {
     for (let i = 0; i < packetlist.length; i++) {
       this.push(packetlist[i]);
@@ -266,17 +269,17 @@ Packetlist.prototype.concat = function (packetlist) {
  * @param {Object} packetClone packetlist clone
  * @returns {Object} new packetlist object with data from packetlist clone
  */
-Packetlist.fromStructuredClone = function(packetlistClone) {
-  const packetlist = new Packetlist();
+List.fromStructuredClone = function(packetlistClone) {
+  const packetlist = new List();
   for (let i = 0; i < packetlistClone.length; i++) {
     packetlist.push(packets.fromStructuredClone(packetlistClone[i]));
     if (packetlist[i].packets.length !== 0) {
       packetlist[i].packets = this.fromStructuredClone(packetlist[i].packets);
     } else {
-      packetlist[i].packets = new Packetlist();
+      packetlist[i].packets = new List();
     }
   }
   return packetlist;
 };
 
-export default Packetlist;
+export default List;
diff --git a/src/packet/public_key.js b/src/packet/public_key.js
index db058770..2cf3ece4 100644
--- a/src/packet/public_key.js
+++ b/src/packet/public_key.js
@@ -16,28 +16,30 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
+ * FIXME
  * Implementation of the Key Material Packet (Tag 5,6,7,14)
  *
  * {@link https://tools.ietf.org/html/rfc4880#section-5.5|RFC4480 5.5}:
  * A key material packet contains all the information about a public or
  * private key.  There are four variants of this packet type, and two
  * major versions.  Consequently, this section is complex.
+ * @requires type/keyid
+ * @requires type/mpi
  * @requires crypto
  * @requires enums
  * @requires util
- * @requires type/keyid
- * @module packet/public_key
  */
 
+import type_keyid from '../type/keyid';
+import type_mpi from '../type/mpi';
 import crypto from '../crypto';
 import enums from '../enums';
 import util from '../util';
-import type_keyid from '../type/keyid';
-import type_mpi from '../type/mpi';
 
 /**
  * A Public-Key packet starts a series of packets that forms an OpenPGP
  * key (sometimes called an OpenPGP certificate).
+ * @memberof module:packet
  * @constructor
  */
 function PublicKey() {
diff --git a/src/packet/public_key_encrypted_session_key.js b/src/packet/public_key_encrypted_session_key.js
index 31351335..1c372c24 100644
--- a/src/packet/public_key_encrypted_session_key.js
+++ b/src/packet/public_key_encrypted_session_key.js
@@ -15,6 +15,22 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires type/ecdh_symkey
+ * @requires type/keyid
+ * @requires type/mpi
+ * @requires crypto
+ * @requires enums
+ * @requires util
+ */
+
+import type_ecdh_symkey from '../type/ecdh_symkey';
+import type_keyid from '../type/keyid';
+import type_mpi from '../type/mpi';
+import crypto from '../crypto';
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Public-Key Encrypted Session Key Packets (Tag 1)
  *
@@ -30,23 +46,7 @@
  * The recipient of the message finds a session key that is encrypted to their
  * public key, decrypts the session key, and then uses the session key to
  * decrypt the message.
- * @requires crypto
- * @requires enums
- * @requires type/ecdh_symkey
- * @requires type/keyid
- * @requires type/mpi
- * @requires util
- * @module packet/public_key_encrypted_session_key
- */
-
-import type_keyid from '../type/keyid.js';
-import util from '../util.js';
-import type_ecdh_symkey from '../type/ecdh_symkey.js';
-import type_mpi from '../type/mpi.js';
-import enums from '../enums.js';
-import crypto from '../crypto';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function PublicKeyEncryptedSessionKey() {
diff --git a/src/packet/public_subkey.js b/src/packet/public_subkey.js
index 75f0f228..f0cd02e4 100644
--- a/src/packet/public_subkey.js
+++ b/src/packet/public_subkey.js
@@ -18,11 +18,10 @@
 /**
  * @requires packet/public_key
  * @requires enums
- * @module packet/public_subkey
  */
 
-import publicKey from './public_key.js';
-import enums from '../enums.js';
+import publicKey from './public_key';
+import enums from '../enums';
 
 /**
  * A Public-Subkey packet (tag 14) has exactly the same format as a
@@ -30,8 +29,9 @@ import enums from '../enums.js';
  * associated with a top-level key.  By convention, the top-level key
  * provides signature services, and the subkeys provide encryption
  * services.
+ * @memberof module:packet
  * @constructor
- * @extends module:packet/public_key
+ * @extends module:packet.PublicKey
  */
 function PublicSubkey() {
   publicKey.call(this);
diff --git a/src/packet/secret_key.js b/src/packet/secret_key.js
index bc7a024e..5dceb7f5 100644
--- a/src/packet/secret_key.js
+++ b/src/packet/secret_key.js
@@ -16,34 +16,35 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
+ * FIXME
  * Implementation of the Key Material Packet (Tag 5,6,7,14)
  *
  * {@link https://tools.ietf.org/html/rfc4880#section-5.5|RFC4480 5.5}:
  * A key material packet contains all the information about a public or
  * private key.  There are four variants of this packet type, and two
  * major versions.  Consequently, this section is complex.
- * @requires crypto
- * @requires enums
  * @requires packet/public_key
  * @requires type/keyid
  * @requires type/s2k
+ * @requires crypto
+ * @requires enums
  * @requires util
- * @module packet/secret_key
  */
 
-import publicKey from './public_key.js';
-import enums from '../enums.js';
-import util from '../util.js';
-import crypto from '../crypto';
-import type_s2k from '../type/s2k.js';
+import publicKey from './public_key';
 import type_keyid from '../type/keyid.js';
+import type_s2k from '../type/s2k';
+import crypto from '../crypto';
+import enums from '../enums';
+import util from '../util';
 
 /**
  * A Secret-Key packet contains all the information that is found in a
  * Public-Key packet, including the public-key material, but also
  * includes the secret-key material after all the public-key fields.
+ * @memberof module:packet
  * @constructor
- * @extends module:packet/public_key
+ * @extends module:packet.PublicKey
  */
 function SecretKey() {
   publicKey.call(this);
diff --git a/src/packet/secret_subkey.js b/src/packet/secret_subkey.js
index f88ade59..74a9c298 100644
--- a/src/packet/secret_subkey.js
+++ b/src/packet/secret_subkey.js
@@ -18,17 +18,17 @@
 /**
  * @requires packet/secret_key
  * @requires enums
- * @module packet/secret_subkey
  */
 
-import secretKey from './secret_key.js';
-import enums from '../enums.js';
+import secretKey from './secret_key';
+import enums from '../enums';
 
 /**
  * A Secret-Subkey packet (tag 7) is the subkey analog of the Secret
  * Key packet and has exactly the same format.
+ * @memberof module:packet
  * @constructor
- * @extends module:packet/secret_key
+ * @extends module:packet.SecretKey
  */
 function SecretSubkey() {
   secretKey.call(this);
diff --git a/src/packet/signature.js b/src/packet/signature.js
index 5e559af8..515e0c2d 100644
--- a/src/packet/signature.js
+++ b/src/packet/signature.js
@@ -15,6 +15,22 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires packet/packet
+ * @requires type/keyid
+ * @requires type/mpi
+ * @requires crypto
+ * @requires enums
+ * @requires util
+ */
+
+import packet from './packet';
+import type_keyid from '../type/keyid.js';
+import type_mpi from '../type/mpi.js';
+import crypto from '../crypto';
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Implementation of the Signature Packet (Tag 2)
  *
@@ -22,23 +38,7 @@
  * A Signature packet describes a binding between some public key and
  * some data.  The most common signatures are a signature of a file or a
  * block of text, and a signature that is a certification of a User ID.
- * @requires crypto
- * @requires enums
- * @requires packet/packet
- * @requires type/keyid
- * @requires type/mpi
- * @requires util
- * @module packet/signature
- */
-
-import util from '../util.js';
-import packet from './packet.js';
-import enums from '../enums.js';
-import crypto from '../crypto';
-import type_mpi from '../type/mpi.js';
-import type_keyid from '../type/keyid.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  * @param {Date} date the creation date of the signature
  */
@@ -363,11 +363,13 @@ Signature.prototype.write_all_sub_packets = function () {
 };
 
 /**
- * creates a string representation of a sub signature packet (See {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC 4880 5.2.3.1})
- * @param {Integer} type subpacket signature type. Signature types as described
- * in {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.2|RFC4880 Section 5.2.3.2}
+ * Creates a string representation of a sub signature packet
+ * @see {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC4880 5.2.3.1}
+ * @see {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.2|RFC4880 5.2.3.2}
+ * @param {Integer} type subpacket signature type.
  * @param {String} data data to be included
- * @returns {String} a string-representation of a sub signature packet (See {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC 4880 5.2.3.1})
+ * @returns {String} a string-representation of a sub signature packet
+ * @private
  */
 function write_sub_packet(type, data) {
   const arr = [];
diff --git a/src/packet/sym_encrypted_aead_protected.js b/src/packet/sym_encrypted_aead_protected.js
index cc98f965..3d0bcc2d 100644
--- a/src/packet/sym_encrypted_aead_protected.js
+++ b/src/packet/sym_encrypted_aead_protected.js
@@ -16,15 +16,9 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
- * Implementation of the Symmetrically Encrypted Authenticated Encryption with
- * Additional Data (AEAD) Protected Data Packet
- *
- * {@link https://tools.ietf.org/html/draft-ford-openpgp-format-00#section-2.1}:
- * AEAD Protected Data Packet
  * @requires crypto
  * @requires enums
  * @requires util
- * @module packet/sym_encrypted_aead_protected
  */
 
 import crypto from '../crypto';
@@ -35,6 +29,12 @@ const VERSION = 1; // A one-octet version number of the data packet.
 const IV_LEN = crypto.gcm.ivLength; // currently only AES-GCM is supported
 
 /**
+ * Implementation of the Symmetrically Encrypted Authenticated Encryption with
+ * Additional Data (AEAD) Protected Data Packet
+ *
+ * {@link https://tools.ietf.org/html/draft-ford-openpgp-format-00#section-2.1}:
+ * AEAD Protected Data Packet
+ * @memberof module:packet
  * @constructor
  */
 function SymEncryptedAEADProtected() {
diff --git a/src/packet/sym_encrypted_integrity_protected.js b/src/packet/sym_encrypted_integrity_protected.js
index 30b749b8..ac5f8fab 100644
--- a/src/packet/sym_encrypted_integrity_protected.js
+++ b/src/packet/sym_encrypted_integrity_protected.js
@@ -16,19 +16,10 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
- * Implementation of the Sym. Encrypted Integrity Protected Data Packet (Tag 18)
- *
- * {@link https://tools.ietf.org/html/rfc4880#section-5.13|RFC4880 5.13}:
- * The Symmetrically Encrypted Integrity Protected Data packet is
- * a variant of the Symmetrically Encrypted Data packet. It is a new feature
- * created for OpenPGP that addresses the problem of detecting a modification to
- * encrypted data. It is used in combination with a Modification Detection Code
- * packet.
  * @requires asmcrypto.js
  * @requires crypto
  * @requires enums
  * @requires util
- * @module packet/sym_encrypted_integrity_protected
  */
 
 import { AES_CFB } from 'asmcrypto.js/src/aes/cfb/exports';
@@ -42,6 +33,15 @@ const Buffer = util.getNodeBuffer();
 const VERSION = 1; // A one-octet version number of the data packet.
 
 /**
+ * Implementation of the Sym. Encrypted Integrity Protected Data Packet (Tag 18)
+ *
+ * {@link https://tools.ietf.org/html/rfc4880#section-5.13|RFC4880 5.13}:
+ * The Symmetrically Encrypted Integrity Protected Data packet is
+ * a variant of the Symmetrically Encrypted Data packet. It is a new feature
+ * created for OpenPGP that addresses the problem of detecting a modification to
+ * encrypted data. It is used in combination with a Modification Detection Code
+ * packet.
+ * @memberof module:packet
  * @constructor
  */
 function SymEncryptedIntegrityProtected() {
diff --git a/src/packet/sym_encrypted_session_key.js b/src/packet/sym_encrypted_session_key.js
index d4aced91..4a4fda1a 100644
--- a/src/packet/sym_encrypted_session_key.js
+++ b/src/packet/sym_encrypted_session_key.js
@@ -15,6 +15,18 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires type/s2k
+ * @requires crypto
+ * @requires enums
+ * @requires util
+ */
+
+import type_s2k from '../type/s2k';
+import crypto from '../crypto';
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Public-Key Encrypted Session Key Packets (Tag 1)
  *
@@ -30,19 +42,7 @@
  * The recipient of the message finds a session key that is encrypted to their
  * public key, decrypts the session key, and then uses the session key to
  * decrypt the message.
- * @requires util
- * @requires crypto
- * @requires enums
- * @requires type/s2k
- * @module packet/sym_encrypted_session_key
- */
-
-import util from '../util.js';
-import type_s2k from '../type/s2k.js';
-import enums from '../enums.js';
-import crypto from '../crypto';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function SymEncryptedSessionKey() {
diff --git a/src/packet/symmetrically_encrypted.js b/src/packet/symmetrically_encrypted.js
index 4150dfd0..0d30760d 100644
--- a/src/packet/symmetrically_encrypted.js
+++ b/src/packet/symmetrically_encrypted.js
@@ -15,6 +15,16 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires config
+ * @requires crypto
+ * @requires enums
+ */
+
+import config from '../config';
+import crypto from '../crypto';
+import enums from '../enums';
+
 /**
  * Implementation of the Symmetrically Encrypted Data Packet (Tag 9)
  *
@@ -24,16 +34,7 @@
  * packets (usually a literal data packet or compressed data packet, but in
  * theory other Symmetrically Encrypted Data packets or sequences of packets
  * that form whole OpenPGP messages).
- * @requires crypto
- * @requires enums
- * @module packet/symmetrically_encrypted
- */
-
-import crypto from '../crypto';
-import enums from '../enums.js';
-import config from '../config';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function SymmetricallyEncrypted() {
diff --git a/src/packet/trust.js b/src/packet/trust.js
index d251f24a..adc0148e 100644
--- a/src/packet/trust.js
+++ b/src/packet/trust.js
@@ -1,3 +1,9 @@
+/**
+ * @requires enums
+ */
+
+import enums from '../enums';
+
 /**
  * Implementation of the Trust Packet (Tag 12)
  *
@@ -12,13 +18,7 @@
  * Trust packets SHOULD NOT be emitted to output streams that are
  * transferred to other users, and they SHOULD be ignored on any input
  * other than local keyring files.
- * @requires enums
- * @module packet/trust
- */
-
-import enums from '../enums.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function Trust() {
diff --git a/src/packet/user_attribute.js b/src/packet/user_attribute.js
index 47dd67e1..6289b2d3 100644
--- a/src/packet/user_attribute.js
+++ b/src/packet/user_attribute.js
@@ -15,6 +15,16 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires packet
+ * @requires enums
+ * @requires util
+ */
+
+import packet from './packet';
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Implementation of the User Attribute Packet (Tag 17)
  *
@@ -31,16 +41,7 @@
  * User Attribute packet.  A simple way to do this is by treating the
  * User Attribute packet as a User ID packet with opaque contents, but
  * an implementation may use any method desired.
- * module packet/user_attribute
- * @requires enums
- * @module packet/user_attribute
- */
-
-import util from '../util.js';
-import packet from './packet.js';
-import enums from '../enums.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function UserAttribute() {
diff --git a/src/packet/userid.js b/src/packet/userid.js
index 9be7fb73..99a5fbdb 100644
--- a/src/packet/userid.js
+++ b/src/packet/userid.js
@@ -15,6 +15,14 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+/**
+ * @requires enums
+ * @requires util
+ */
+
+import enums from '../enums';
+import util from '../util';
+
 /**
  * Implementation of the User ID Packet (Tag 13)
  *
@@ -23,15 +31,7 @@
  * includes an RFC 2822 [RFC2822] mail name-addr, but there are no
  * restrictions on its content.  The packet length in the header
  * specifies the length of the User ID.
- * @requires util
- * @requires enums
- * @module packet/userid
- */
-
-import util from '../util.js';
-import enums from '../enums.js';
-
-/**
+ * @memberof module:packet
  * @constructor
  */
 function Userid() {