Updated the docs for extend/restore footprint ops. (#752)

* Updated the docs for extend/restore footprint ops.

Extend TTL doc was incorrect, and restore doc lacked some important details.

Author: dmkozh

src/operations/extend_footprint_ttl.js

@@ -1,29 +1,38 @@
 import xdr from '../xdr';
 
 /**
- * Builds an operation to bump the time-to-live of a footprint (read and written
- * ledger keys). Its only parameter is the new, absolute ledger sequence number
- * at which the entry will expire.
+ * Builds an operation to bump the time-to-live (TTL) of the ledger keys. The
+ * keys for extension have to be provided in the read-only footprint of
+ * the transaction.
  *
- * The footprint itself is derived from the transaction (see
+ * The only parameter of the operation itself is the new minimum TTL for
+ * all the provided entries. If an entry already has a higher TTL, then it
+ * will just be skipped.
+ *
+ * TTL is the number of ledgers from the current ledger (exclusive) until
+ * the last ledger the entry is still considered alive (inclusive). Thus
+ * the exact ledger until the entries will live will only be determined
+ * when transaction has been applied.
+ *
+ * The footprint has to be specified in the transaction. See
  * {@link TransactionBuilder}'s `opts.sorobanData` parameter, which is a
  * {@link xdr.SorobanTransactionData} instance that contains fee data & resource
- * usage as part of {@link xdr.SorobanResources}).
+ * usage as part of {@link xdr.SorobanResources}.
  *
  * @function
  * @alias Operation.extendFootprintTtl
  *
  * @param {object} opts - object holding operation parameters
- * @param {number} opts.extendTo - the absolute ledger sequence number at which
- *     the transaction's ledger keys will now expire
+ * @param {number} opts.extendTo - the minimum TTL that all the entries in
+ *    the read-only footprint will have
  * @param {string} [opts.source] - an optional source account
  *
  * @returns {xdr.Operation} an Extend Footprint TTL operation
  *    (xdr.ExtendFootprintTTLOp)
  */
 export function extendFootprintTtl(opts) {
   if ((opts.extendTo ?? -1) <= 0) {
-    throw new RangeError("extendTo isn't a ledger quantity (uint32)");
+    throw new RangeError('extendTo has to be positive');
   }
 
   const extendFootprintOp = new xdr.ExtendFootprintTtlOp({

src/operations/restore_footprint.js

@@ -1,14 +1,18 @@
 import xdr from '../xdr';
 
 /**
- * Builds a footprint restoration operation.
+ * Builds an operation to restore the archived ledger entries specified
+ * by the ledger keys.
+ *
+ * The ledger keys to restore are specified separately from the operation
+ * in read-write footprint of the transaction.
  *
  * It takes no parameters because the relevant footprint is derived from the
- * transaction itself (see {@link TransactionBuilder}'s `opts.sorobanData`
+ * transaction itself. See {@link TransactionBuilder}'s `opts.sorobanData`
  * parameter (or {@link TransactionBuilder.setSorobanData} /
  * {@link TransactionBuilder.setLedgerKeys}), which is a
  * {@link xdr.SorobanTransactionData} instance that contains fee data & resource
- * usage as part of {@link xdr.SorobanTransactionData}).
+ * usage as part of {@link xdr.SorobanTransactionData}.
  *
  * @function
  * @alias Operation.restoreFootprint

test/unit/operations/extend_restore_test.js

@@ -14,7 +14,7 @@ describe('Operation', function () {
 
       expect(() => {
         StellarBase.Operation.extendFootprintTtl({ extendTo: 0 });
-      }).to.throw(/ledger quantity/i);
+      }).to.throw(/has to be positive/i);
     });
   });