update README to demonstrate detached signature use, some documentation fixes

README.md

@@ -185,33 +185,41 @@ openpgp.verify(options).then(function(verified) {
 });
 ```
 
-#### Create and verify *detached* signatures for binary data
+#### Create and verify *detached* signatures
 
 ```js
-var content, detachedSig, validity;
+var options, cleartext, detachedSig, validity;
 
 var pubkey = '-----BEGIN PGP PUBLIC KEY BLOCK ... END PGP PUBLIC KEY BLOCK-----';
 var privkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK-----';
 ```
 
 ```js
-content = 'Hello, World!';                               // input as String
-var privateKeys = openpgp.key.readArmored(privkey).keys; // for signing
-var bytes = openpgp.util.str2Uint8Array(content);        // convert text to binary
-var message = openpgp.message.fromBinary(bytes);
-var signedMessage = message.sign(privateKeys);
-var signature = signedMessage.packets.filterByTag(openpgp.enums.packet.signature);
-var armoredMessage = openpgp.armor.encode(openpgp.enums.armor.message, signature.write());
-armoredMessage = armoredMessage.replace('-----BEGIN PGP MESSAGE-----\r\n', '-----BEGIN PGP SIGNATURE-----\r\n');
-armoredMessage = armoredMessage.replace('-----END PGP MESSAGE-----\r\n', '-----END PGP SIGNATURE-----\r\n');
-detachedSig = armoredMessage; // '-----BEGIN PGP SIGNATURE ... END PGP SIGNATURE-----'
+options = {
+    data: 'Hello, World!',                             // input as String (or Uint8Array)
+    privateKeys: openpgp.key.readArmored(privkey).keys, // for signing
+    detached: true
+};
+
+openpgp.sign(options).then(function(signed) {
+    cleartext = signed.data;
+    detachedSig = signed.signature;
+});
 ```
 
 ```js
-var publicKeys = openpgp.key.readArmored(pubkey).keys; // for verifying signatures
-var msg = openpgp.message.readSignedContent(content, detachedSig);
-var result = msg.verify(publicKeys);
-validity = result[0].valid; // true
+options = {
+    message: openpgp.cleartext.readArmored(cleartext), // parse armored message
+    signature: openpgp.signature.readArmored(detachedSig), // parse detached signature
+    publicKeys: openpgp.key.readArmored(pubkey).keys   // for verification
+};
+
+openpgp.verify(options).then(function(verified) {
+    validity = verified.signatures[0].valid; // true
+    if (validity) {
+        console.log('signed by key id ' + verified.signatures[0].keyid.toHex());
+    }
+});
 ```
 
 ### Documentation

src/cleartext.js

@@ -36,7 +36,7 @@ import * as sigModule from './signature.js';
  * @classdesc Class that represents an OpenPGP cleartext signed message.
  * See {@link http://tools.ietf.org/html/rfc4880#section-7}
  * @param  {String}     text       The cleartext of the signed message
- * @param  {module:Signature} signature       The detached signature or an empty signature if message not yet signed
+ * @param  {module:signature} signature       The detached signature or an empty signature if message not yet signed
  */
 
 export function CleartextMessage(text, signature) {

src/openpgp.js

@@ -114,7 +114,7 @@ export function generateKey({ userIds=[], passphrase, numBits=2048, unlocked=fal
 }
 
 /**
- * Generates a new OpenPGP key pair. Currently only supports RSA keys. Primary and subkey will be of same type.
+ * Reformats signature packets for a key and rewraps key object.
  * @param  {Array<Object>} userIds   array of user IDs e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }]
  * @param  {String} passphrase       (optional) The passphrase used to encrypt the resulting private key
  * @param  {Boolean} unlocked        (optional) If the returned secret part of the generated key is unlocked
@@ -272,6 +272,7 @@ export function decrypt({ message, privateKey, publicKeys, sessionKey, password,
  * @param  {String} data                        cleartext input to be signed
  * @param  {Key|Array<Key>} privateKeys         array of keys or single key with decrypted secret key data to sign cleartext
  * @param  {Boolean} armor                      (optional) if the return value should be ascii armored or the message object
+ * @param  {Boolean} detached                   (optional) if the return value should contain a detached signature
  * @return {Promise<Object>}                    signed cleartext in the form:
  *                                                {data: ASCII armored message if 'armor' is true,
  *                                                message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true}

src/signature.js

@@ -55,7 +55,7 @@ Signature.prototype.armor = function() {
 /**
  * reads an OpenPGP armored signature and returns a signature object
  * @param {String} armoredText text to be parsed
- * @return {module:signature~Signature} new signature object
+ * @return {Signature} new signature object
  * @static
  */
 export function readArmored(armoredText) {