diff --git a/core/src/main/java/com/google/bitcoin/core/Address.java b/core/src/main/java/com/google/bitcoin/core/Address.java
index 4e73110a..e826b2d5 100644
--- a/core/src/main/java/com/google/bitcoin/core/Address.java
+++ b/core/src/main/java/com/google/bitcoin/core/Address.java
@@ -17,8 +17,9 @@
 package com.google.bitcoin.core;
 
 /**
- * A Bitcoin address is derived from an elliptic curve public key and a set of network parameters.
- * It has several possible representations:<p>
+ * <p>A Bitcoin address is derived from an elliptic curve public key and a set of network parameters. Not to be confused
+ * with a {@link PeerAddress} or {@link AddressMessage} which are about network (TCP) addresses.
+ * It has several possible representations:</p>
  *
  * <ol>
  * <li>The raw public key bytes themselves.
diff --git a/core/src/main/java/com/google/bitcoin/core/AddressMessage.java b/core/src/main/java/com/google/bitcoin/core/AddressMessage.java
index 998f4539..64199b0f 100644
--- a/core/src/main/java/com/google/bitcoin/core/AddressMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/AddressMessage.java
@@ -6,6 +6,11 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * Represents an "addr" message on the P2P network, which contains broadcast advertisements of other peers. This is
+ * one of the ways peers can find each other without using the DNS or IRC discovery mechansisms. However storing and
+ * using addr messages is not presently implemented.
+ */
 public class AddressMessage extends Message {
     private static final long serialVersionUID = 8058283864924679460L;
     private static final long MAX_ADDRESSES = 1024;
diff --git a/core/src/main/java/com/google/bitcoin/core/Base58.java b/core/src/main/java/com/google/bitcoin/core/Base58.java
index 58d6bf7a..8584e76b 100644
--- a/core/src/main/java/com/google/bitcoin/core/Base58.java
+++ b/core/src/main/java/com/google/bitcoin/core/Base58.java
@@ -21,14 +21,14 @@ import java.math.BigInteger;
 import java.util.Arrays;
 
 /**
- * A custom form of base58 is used to encode BitCoin addresses. Note that this is not the same base58 as used by
- * Flickr, which you may see reference to around the internet.<p>
+ * <p>Base58 is a way to encode Bitcoin addresses as numbers and letters. Note that this is not the same base58 as used by
+ * Flickr, which you may see reference to around the internet.</p>
  *
- * Satoshi says: why base-58 instead of standard base-64 encoding?<p>
+ * <p>Satoshi says: why base-58 instead of standard base-64 encoding?<p>
  *
  * <ul>
  * <li>Don't want 0OIl characters that look the same in some fonts and
- *    could be used to create visually identical looking account numbers.</li>
+ *     could be used to create visually identical looking account numbers.</li>
  * <li>A string with non-alphanumeric characters is not as easily accepted as an account number.</li>
  * <li>E-mail usually won't line-break if there's no punctuation to break at.</li>
  * <li>Doubleclicking selects the whole number as one word if it's all alphanumeric.</li>
diff --git a/core/src/main/java/com/google/bitcoin/core/Block.java b/core/src/main/java/com/google/bitcoin/core/Block.java
index dabfc18d..e273ae1d 100644
--- a/core/src/main/java/com/google/bitcoin/core/Block.java
+++ b/core/src/main/java/com/google/bitcoin/core/Block.java
@@ -34,9 +34,11 @@ import static com.google.bitcoin.core.Utils.doubleDigest;
 import static com.google.bitcoin.core.Utils.doubleDigestTwoBuffers;
 
 /**
- * A block is the foundation of the BitCoin system. It records a set of {@link Transaction}s together with some data
- * that links it into a place in the global block chain, and proves that a difficult calculation was done over its
- * contents. See the BitCoin technical paper for more detail on blocks. <p/>
+ * <p>A block is a group of transactions, and is one of the fundamental data structures of the Bitcoin system.
+ * It records a set of {@link Transaction}s together with some data that links it into a place in the global block
+ * chain, and proves that a difficult calculation was done over its contents. See
+ * <a href="http://www.bitcoin.org/bitcoin.pdf">the Bitcoin technical paper</a> for
+ * more detail on blocks. <p/>
  *
  * To get a block, you can either build one from the raw bytes you can get from another implementation, or request one
  * specifically using {@link Peer#getBlock(Sha256Hash)}, or grab one from a downloaded {@link BlockChain}.
diff --git a/core/src/main/java/com/google/bitcoin/core/GetAddrMessage.java b/core/src/main/java/com/google/bitcoin/core/GetAddrMessage.java
index a165fb72..e00287c3 100644
--- a/core/src/main/java/com/google/bitcoin/core/GetAddrMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/GetAddrMessage.java
@@ -16,6 +16,10 @@
 
 package com.google.bitcoin.core;
 
+/**
+ * Represents the "getaddr" P2P protocol message, which requests network {@link AddressMessage}s from a peer. Not to
+ * be confused with {@link Address} which is sort of like an account number.
+ */
 public class GetAddrMessage extends EmptyMessage {
     private static final long serialVersionUID = 6204437624599661503L;
 
diff --git a/core/src/main/java/com/google/bitcoin/core/GetBlocksMessage.java b/core/src/main/java/com/google/bitcoin/core/GetBlocksMessage.java
index 9e233c06..7865f1cf 100644
--- a/core/src/main/java/com/google/bitcoin/core/GetBlocksMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/GetBlocksMessage.java
@@ -21,6 +21,10 @@ import java.io.OutputStream;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents the "getblocks" P2P network message, which requests the hashes of the parts of the block chain we're
+ * missing. Those blocks can then be downloaded with a {@link GetDataMessage}.
+ */
 public class GetBlocksMessage extends Message {
     private static final long serialVersionUID = 3479412877853645644L;
     protected long version;
diff --git a/core/src/main/java/com/google/bitcoin/core/GetDataMessage.java b/core/src/main/java/com/google/bitcoin/core/GetDataMessage.java
index b091b675..2f657637 100644
--- a/core/src/main/java/com/google/bitcoin/core/GetDataMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/GetDataMessage.java
@@ -16,6 +16,10 @@
 
 package com.google.bitcoin.core;
 
+/**
+ * Represents the "getdata" P2P network message, which requests the contents of blocks or transactions given their
+ * hashes.
+ */
 public class GetDataMessage extends ListMessage {
     private static final long serialVersionUID = 2754681589501709887L;
 
diff --git a/core/src/main/java/com/google/bitcoin/core/InventoryMessage.java b/core/src/main/java/com/google/bitcoin/core/InventoryMessage.java
index 490dfca1..ebacc882 100644
--- a/core/src/main/java/com/google/bitcoin/core/InventoryMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/InventoryMessage.java
@@ -16,6 +16,12 @@
 
 package com.google.bitcoin.core;
 
+/**
+ * <p>Represents the "inv" P2P network message. An inv contains a list of hashes of either blocks or transactions. It's
+ * a bandwidth optimization - on receiving some data, a (fully validating) peer sends every connected peer an inv
+ * containing the hash of what it saw. It'll only transmit the full thing if a peer asks for it with a
+ * {@link GetDataMessage}.</p>
+ */
 public class InventoryMessage extends ListMessage {
     private static final long serialVersionUID = -7050246551646107066L;
 
diff --git a/core/src/main/java/com/google/bitcoin/core/ListMessage.java b/core/src/main/java/com/google/bitcoin/core/ListMessage.java
index 48700c42..5189e6b9 100644
--- a/core/src/main/java/com/google/bitcoin/core/ListMessage.java
+++ b/core/src/main/java/com/google/bitcoin/core/ListMessage.java
@@ -23,7 +23,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Abstract superclass of classes with list based payload, i.e. InventoryMessage and GetDataMessage.
+ * Abstract superclass of classes with list based payload, ie InventoryMessage and GetDataMessage.
  */
 public abstract class ListMessage extends Message {
     private static final long serialVersionUID = -4275896329391143643L;
diff --git a/core/src/main/java/com/google/bitcoin/core/MemoryPool.java b/core/src/main/java/com/google/bitcoin/core/MemoryPool.java
index 5657ddbe..ff6eb0ef 100644
--- a/core/src/main/java/com/google/bitcoin/core/MemoryPool.java
+++ b/core/src/main/java/com/google/bitcoin/core/MemoryPool.java
@@ -29,15 +29,15 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * Tracks transactions that are being announced across the network. Typically one is created for you by a PeerGroup
- * and then given to each Peer to update. The current purpose is to let Peers update the confidence (number of peers
- * broadcasting). It helps address an attack scenario in which a malicious remote peer (or several) feeds you
- * invalid transactions, eg, ones that spend coins which don't exist. If you don't see most of the peers announce the
- * transaction within a reasonable time, it may be that the TX is not valid. Alternatively, an attacker may control
- * your entire internet connection: in this scenario counting broadcasting peers does not help you.<p>
+ * <p>Tracks transactions that are being announced across the network. Typically one is created for you by a
+ * {@link PeerGroup} and then given to each Peer to update. The current purpose is to let Peers update the confidence
+ * (number of peers broadcasting). It helps address an attack scenario in which a malicious remote peer (or several)
+ * feeds you invalid transactions, eg, ones that spend coins which don't exist. If you don't see most of the peers
+ * announce the transaction within a reasonable time, it may be that the TX is not valid. Alternatively, an attacker
+ * may control your entire internet connection: in this scenario counting broadcasting peers does not help you.</p>
  *
- * It is <b>not</b> at this time directly equivalent to the Satoshi clients memory pool, which tracks
- * all transactions not currently included in the best chain - it's simply a cache.
+ * <p>It is <b>not</b> at this time directly equivalent to the Satoshi clients memory pool, which tracks
+ * all transactions not currently included in the best chain - it's simply a cache.</p>
  */
 public class MemoryPool {
     private static final Logger log = LoggerFactory.getLogger(MemoryPool.class);
diff --git a/core/src/main/java/com/google/bitcoin/core/Message.java b/core/src/main/java/com/google/bitcoin/core/Message.java
index 1dd72b17..40c16e0f 100644
--- a/core/src/main/java/com/google/bitcoin/core/Message.java
+++ b/core/src/main/java/com/google/bitcoin/core/Message.java
@@ -26,11 +26,9 @@ import java.util.Arrays;
 import static com.google.common.base.Preconditions.checkState;
 
 /**
- * A Message is a data structure that can be serialized/deserialized using both the BitCoin proprietary serialization
+ * <p>A Message is a data structure that can be serialized/deserialized using both the Bitcoin proprietary serialization
  * format and built-in Java object serialization. Specific types of messages that are used both in the block chain,
- * and on the wire, are derived from this class.
- * <p/>
- * This class is not useful for library users. If you want to talk to the network see the {@link Peer} class.
+ * and on the wire, are derived from this class.</p>
  */
 public abstract class Message implements Serializable {
     private static final Logger log = LoggerFactory.getLogger(Message.class);
diff --git a/core/src/main/java/com/google/bitcoin/core/Peer.java b/core/src/main/java/com/google/bitcoin/core/Peer.java
index 712ea863..6fdc20ef 100644
--- a/core/src/main/java/com/google/bitcoin/core/Peer.java
+++ b/core/src/main/java/com/google/bitcoin/core/Peer.java
@@ -37,7 +37,7 @@ import java.util.concurrent.*;
  * <p>{@link Peer#getHandler()} is part of a Netty Pipeline with a Bitcoin serializer downstream of it.
  */
 public class Peer {
-    public interface PeerLifecycleListener {
+    interface PeerLifecycleListener {
         /** Called when the peer is connected */
         public void onPeerConnected(Peer peer);
         /** Called when the peer is disconnected */
@@ -45,7 +45,6 @@ public class Peer {
     }
 
     private static final Logger log = LoggerFactory.getLogger(Peer.class);
-    public static final int CONNECT_TIMEOUT_MSEC = 60000;
 
     private final NetworkParameters params;
     private final BlockChain blockChain;
@@ -118,11 +117,11 @@ public class Peer {
         return eventListeners.remove(listener);
     }
 
-    public synchronized void addLifecycleListener(PeerLifecycleListener listener) {
+    synchronized void addLifecycleListener(PeerLifecycleListener listener) {
         lifecycleListeners.add(listener);
     }
 
-    public synchronized boolean removeLifecycleListener(PeerLifecycleListener listener) {
+    synchronized boolean removeLifecycleListener(PeerLifecycleListener listener) {
         return lifecycleListeners.remove(listener);
     }
 
diff --git a/core/src/main/java/com/google/bitcoin/core/PeerAddress.java b/core/src/main/java/com/google/bitcoin/core/PeerAddress.java
index 83e58c43..d44a52e8 100644
--- a/core/src/main/java/com/google/bitcoin/core/PeerAddress.java
+++ b/core/src/main/java/com/google/bitcoin/core/PeerAddress.java
@@ -28,7 +28,7 @@ import static com.google.bitcoin.core.Utils.uint64ToByteStreamLE;
 
 /**
  * A PeerAddress holds an IP address and port number representing the network location of
- * a peer in the BitCoin P2P network. It exists primarily for serialization purposes.
+ * a peer in the Bitcoin P2P network. It exists primarily for serialization purposes.
  */
 public class PeerAddress extends ChildMessage {
     private static final long serialVersionUID = 7501293709324197411L;
diff --git a/core/src/main/java/com/google/bitcoin/core/Script.java b/core/src/main/java/com/google/bitcoin/core/Script.java
index ab3d28a0..5c30a361 100644
--- a/core/src/main/java/com/google/bitcoin/core/Script.java
+++ b/core/src/main/java/com/google/bitcoin/core/Script.java
@@ -42,14 +42,16 @@ class ScriptChunk {
 }
 
 /**
- * Bitcoin transactions don't specify what they do directly. Instead <a href="https://en.bitcoin.it/wiki/Script">a
- * small binary stack language</a> is used to define programs that when evaluated return whether the transaction
- * "accepts" or rejects the other transactions connected to it.<p>
+ * Instructions for redeeming a payment.
  *
- * BitcoinJ does not evaluate/run scripts. The reason is that doing so requires the connected transactions, ie, all
+ * <p>Bitcoin transactions don't specify what they do directly. Instead <a href="https://en.bitcoin.it/wiki/Script">a
+ * small binary stack language</a> is used to define programs that when evaluated return whether the transaction
+ * "accepts" or rejects the other transactions connected to it.</p>
+ *
+ * <p>bitcoinj does not evaluate/run scripts. The reason is that doing so requires the connected transactions, ie, all
  * transactions, and as a lightweight/SPV client we don't store them all. Instead tx validity is decided by miners
  * and we rely purely on the majority consensus to determine if the scripts are valid. This class therefore just lets
- * you manipulate and parse them.
+ * you manipulate and parse them.</p>
  */
 public class Script {
     // Some constants used for decoding the scripts, copied from the reference client
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 25e5535f..230bd5ea 100644
--- a/core/src/main/java/com/google/bitcoin/core/Transaction.java
+++ b/core/src/main/java/com/google/bitcoin/core/Transaction.java
@@ -28,19 +28,18 @@ import java.util.*;
 import static com.google.bitcoin.core.Utils.*;
 
 /**
- * A transaction represents the movement of coins from some addresses to some other addresses. It can also represent
- * the minting of new coins. A Transaction object corresponds to the equivalent in the BitCoin C++ implementation.<p>
+ * <p>A transaction represents the movement of coins from some addresses to some other addresses. It can also represent
+ * the minting of new coins. A Transaction object corresponds to the equivalent in the Bitcoin C++ implementation.</p>
  *
- * It implements TWO serialization protocols - the Bitcoin proprietary format which is identical to the C++
- * implementation and is used for reading/writing transactions to the wire and for hashing. It also implements Java
- * serialization which is used for the wallet. This allows us to easily add extra fields used for our own accounting
- * or UI purposes.<p>
- *     
- * All Bitcoin transactions are at risk of being reversed, though the risk is much less than with traditional payment 
+ * <p>Transactions are the fundamental atoms of Bitcoin and have many powerful features. Read
+ * <a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTransactions">"Working with transactions"</a> in the
+ * documentation to learn more about how to use this class.</p>
+ *
+ * <p>All Bitcoin transactions are at risk of being reversed, though the risk is much less than with traditional payment
  * systems. Transactions have <i>confidence levels</i>, which help you decide whether to trust a transaction or not.
  * Whether to trust a transaction is something that needs to be decided on a case by case basis - a rule that makes 
  * sense for selling MP3s might not make sense for selling cars, or accepting payments from a family member. If you
- * are building a wallet, how to present confidence to your users is something to consider carefully.
+ * are building a wallet, how to present confidence to your users is something to consider carefully.</p>
  */
 public class Transaction extends ChildMessage implements Serializable {
     private static final Logger log = LoggerFactory.getLogger(Transaction.class);
diff --git a/core/src/main/java/com/google/bitcoin/core/TransactionConfidence.java b/core/src/main/java/com/google/bitcoin/core/TransactionConfidence.java
index ee93fe7c..cb670673 100644
--- a/core/src/main/java/com/google/bitcoin/core/TransactionConfidence.java
+++ b/core/src/main/java/com/google/bitcoin/core/TransactionConfidence.java
@@ -161,10 +161,13 @@ public class TransactionConfidence implements Serializable {
     };
 
     /**
-     * A confidence listener is informed when the level of confidence in a transaction is updated by something, like
+     * <p>A confidence listener is informed when the level of {@link TransactionConfidence} is updated by something, like
      * for example a {@link Wallet}. You can add listeners to update your user interface or manage your order tracking
-     * system when confidence levels pass a certain threshold. <b>Note that confidence can go down as well as up.</b>.
-     * During listener execution, it's safe to remove the current listener but not others.
+     * system when confidence levels pass a certain threshold. <b>Note that confidence can go down as well as up.</b>
+     * For example, this can happen if somebody is doing a double-spend attack against you. Whilst it's unlikely, your
+     * code should be able to handle that in order to be correct.</p>
+     *
+     * <p>During listener execution, it's safe to remove the current listener but not others.</p>
      */
     public interface Listener {
         public void onConfidenceChanged(Transaction tx);
diff --git a/core/src/main/java/com/google/bitcoin/core/Wallet.java b/core/src/main/java/com/google/bitcoin/core/Wallet.java
index 81be8355..e55500fc 100644
--- a/core/src/main/java/com/google/bitcoin/core/Wallet.java
+++ b/core/src/main/java/com/google/bitcoin/core/Wallet.java
@@ -40,6 +40,9 @@ import static com.google.common.base.Preconditions.*;
  * it is able to create new transactions that spend the recorded transactions, and this is the fundamental operation
  * of the Bitcoin protocol.</p>
  *
+ * <p>To learn more about this class, read <b><a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTheWallet">
+ *     working with the wallet.</a></b></p>
+ *
  * <p>To fill up a Wallet with transactions, you need to use it in combination with a {@link BlockChain} and various
  * other objects, see the <a href="http://code.google.com/p/bitcoinj/wiki/GettingStarted">Getting started</a> tutorial
  * on the website to learn more about how to set everything up.</p>
@@ -51,9 +54,6 @@ import static com.google.common.base.Preconditions.*;
  * the wallet is changing very fast (eg due to a block chain sync). See
  * {@link Wallet#autosaveToFile(java.io.File, long, java.util.concurrent.TimeUnit, com.google.bitcoin.core.Wallet.AutosaveEventListener)}
  * for more information about this.</p>
- *
- * <p><a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTheWallet">Learn more about working with the wallet.
- * </a></p>
  */
 public class Wallet implements Serializable {
     private static final Logger log = LoggerFactory.getLogger(Wallet.class);
diff --git a/core/src/main/java/com/google/bitcoin/core/WalletEventListener.java b/core/src/main/java/com/google/bitcoin/core/WalletEventListener.java
index 1e46421c..10a3baf1 100644
--- a/core/src/main/java/com/google/bitcoin/core/WalletEventListener.java
+++ b/core/src/main/java/com/google/bitcoin/core/WalletEventListener.java
@@ -92,17 +92,13 @@ public interface WalletEventListener {
      * </ol><p>
      *
      * To find if the transaction is dead, you can use <tt>tx.getConfidence().getConfidenceType() ==
-     * TransactionConfidence.ConfidenceType.OVERRIDDEN_BY_DOUBLE_SPEND</tt>. If it is, you should notify the user
+     * TransactionConfidence.ConfidenceType.DEAD</tt>. If it is, you should notify the user
      * in some way so they know the thing they bought may not arrive/the thing they sold should not be dispatched.
-     *
-     * @param wallet
-     * @param tx
      */
     void onTransactionConfidenceChanged(Wallet wallet, Transaction tx);
 
     /**
      * Called by the {@link Wallet#addKey(ECKey)} method on whatever the calling thread was.
-     * @param key
      */
     void onKeyAdded(ECKey key);
 }