From 12e1c3f6bd564e7a81701f56136943291f127232 Mon Sep 17 00:00:00 2001
From: Carlos Lopez-Camey <c.lopez@kmels.net>
Date: Tue, 29 Jul 2014 12:31:08 -0600
Subject: [PATCH] Improve javadocs, revert unnecessary unmodifiable list

---
 .../com/google/bitcoin/core/Transaction.java  | 19 +++++++-----
 .../bitcoin/core/TransactionOutput.java       | 31 ++++++++++++++-----
 2 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/core/src/main/java/com/google/bitcoin/core/Transaction.java b/core/src/main/java/com/google/bitcoin/core/Transaction.java
index aee0fb0e..00148384 100644
--- a/core/src/main/java/com/google/bitcoin/core/Transaction.java
+++ b/core/src/main/java/com/google/bitcoin/core/Transaction.java
@@ -1195,21 +1195,24 @@ public class Transaction extends ChildMessage implements Serializable {
         return Collections.unmodifiableList(outputs);
     }
 
-    /** Returns an unmodifiable list of outputs matching a wallet or of watched wallet outputs
-     * i.e., transaction outputs whose script's pubkey belongs to the given wallet or whose script is watched by the wallet.
-     * including spent outputs **/
-    public List<TransactionOutput> getWalletOutputs(Wallet w){
+    /**
+     * <p>Returns the list of transacion outputs, whether spent or unspent, that match a wallet by address or that are
+     * watched by a wallet, i.e., transaction outputs whose script's address is controlled by the wallet and transaction
+     * outputs whose script is watched by the wallet./p>
+     *
+     * @param wallet The wallet that controls addresses and watches scripts.
+     * @return linked list of outputs relevant to the wallet in this transaction
+     */
+    public List<TransactionOutput> getWalletOutputs(Wallet wallet){
         maybeParse();
-
         List<TransactionOutput> walletOutputs = new LinkedList<TransactionOutput>();
-
         Coin v = Coin.ZERO;
         for (TransactionOutput o : outputs) {
-            if (!o.isMineOrWatched(w)) continue;
+            if (!o.isMineOrWatched(wallet)) continue;
             walletOutputs.add(o);
         }
 
-        return Collections.unmodifiableList(walletOutputs);
+        return walletOutputs;
     }
 
     /** Randomly re-orders the transaction outputs: good for privacy */
diff --git a/core/src/main/java/com/google/bitcoin/core/TransactionOutput.java b/core/src/main/java/com/google/bitcoin/core/TransactionOutput.java
index 12c5e27e..eef3ae03 100644
--- a/core/src/main/java/com/google/bitcoin/core/TransactionOutput.java
+++ b/core/src/main/java/com/google/bitcoin/core/TransactionOutput.java
@@ -137,22 +137,37 @@ public class TransactionOutput extends ChildMessage implements Serializable {
         return script;
     }
 
-    /*
-     * If the output script pays to an address, returns the address i.e., a base-58 hash of the public key
-     * in the Pay-To-Public-Key-Hash (P2PKH) script
+    /**
+     * <p>If the output script pays to an address as in <a href="https://bitcoin.org/en/developer-guide#term-p2pkh">
+     * P2PKH</a>, return the address of the receiver, i.e., a base58 encoded hash of the public key in the script. </p>
+     *
+     * @param networkParameters needed to specify an address
+     * @return null, if the output script is not the form <i>OP_DUP OP_HASH160 <PubkeyHash> OP_EQUALVERIFY OP_CHECKSIG</i>,
+     * i.e., not P2PKH
+     * @return an address made out of the public key hash
      */
-    public Address getAddressFromPubKey(NetworkParameters networkParameters) throws ScriptException{
+    @Nullable
+    public Address getAddressFromP2PKHScript(NetworkParameters networkParameters) throws ScriptException{
         if (getScriptPubKey().isSentToAddress())
             return getScriptPubKey().getToAddress(networkParameters);
 
         return null;
     }
 
-    /*
-     * If the output script pays to an script, returns the address i.e., a 20-byte hash of the script
-     * in the Pay-To-Public-Script-Hash (P2PSH) script
+    /**
+     * <p>If the output script pays to a redeem script, return the address of the redeem script as described by,
+     * i.e., a base58 encoding of [one-byte version][20-byte hash][4-byte checksum], where the 20-byte hash refers to
+     * the redeem script.</p>
+     *
+     * <p>P2SH is described by <a href="https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki">BIP 16</a> and
+     * <a href="https://bitcoin.org/en/developer-guide#p2sh-scripts">documented in the Bitcoin Developer Guide</a>.</p>
+     *
+     * @param networkParameters needed to specify an address
+     * @return null if the output script does not pay to a script hash
+     * @return an address that belongs to the redeem script
      */
-    public Address getAddressFromScript(NetworkParameters networkParameters) throws ScriptException{
+    @Nullable
+    public Address getAddressFromP2SH(NetworkParameters networkParameters) throws ScriptException{
         if (getScriptPubKey().isPayToScriptHash())
             return getScriptPubKey().getToAddress(networkParameters);