--- a/README.rst
+++ b/README.rst
@@ -12,7 +12,7 @@
 
 - Compatibility with Linux (both GNOME and KDE), MacOSX and Windows
 
-- All functionality of the original client, including taskbar icon/menu
+- All functionality of the original client, including taskbar icon/menu and wallet encryption
 
 - Splash screen
 
@@ -44,7 +44,7 @@
 
 - Start at system start
 
-- Support more languages
+- Support more languages (please send translations)
 
 Build instructions 
 ===================

--- a/src/qt/bitcoinamountfield.cpp
+++ b/src/qt/bitcoinamountfield.cpp
@@ -161,6 +161,7 @@
 
     if(valid)
     {
+        // If value was valid, re-place it in the widget with the new unit
         setValue(currentValue);
     }
     else

--- a/src/qt/bitcoingui.cpp
+++ b/src/qt/bitcoingui.cpp
@@ -602,7 +602,7 @@
 
 void BitcoinGUI::unlockWallet()
 {
-    // Unlock wallet if needed
+    // Unlock wallet when requested by wallet model
     if(walletModel->getEncryptionStatus() == WalletModel::Locked)
     {
         AskPassphraseDialog dlg(AskPassphraseDialog::Unlock, this);

--- a/src/qt/walletmodel.h
+++ b/src/qt/walletmodel.h
@@ -23,7 +23,7 @@
 public:
     explicit WalletModel(CWallet *wallet, OptionsModel *optionsModel, QObject *parent = 0);
 
-    enum StatusCode
+    enum StatusCode // Returned by sendCoins
     {
         OK,
         InvalidAmount,
@@ -31,7 +31,7 @@
         AmountExceedsBalance,
         AmountWithFeeExceedsBalance,
         DuplicateAddress,
-        TransactionCreationFailed,
+        TransactionCreationFailed, // Error returned when wallet is still locked
         TransactionCommitFailed,
         Aborted,
         MiscError
@@ -86,12 +86,9 @@
 
         bool isValid() const { return valid; }
 
-        UnlockContext(const UnlockContext& obj)
-        { CopyFrom(obj); }
-    private:
-        UnlockContext& operator=(const UnlockContext& rhs)
-        { CopyFrom(rhs); return *this; }
-
+        // Copy operator and constructor transfer the context
+        UnlockContext(const UnlockContext& obj) { CopyFrom(obj); }
+        UnlockContext& operator=(const UnlockContext& rhs) { CopyFrom(rhs); return *this; }
     private:
         WalletModel *wallet;
         bool valid;
@@ -112,15 +109,25 @@
     AddressTableModel *addressTableModel;
     TransactionTableModel *transactionTableModel;
 
+    // Cache some values to be able to detect changes
     qint64 cachedBalance;
     qint64 cachedUnconfirmedBalance;
     qint64 cachedNumTransactions;
     EncryptionStatus cachedEncryptionStatus;
 
 signals:
+    // Signal that balance in wallet changed
     void balanceChanged(qint64 balance, qint64 unconfirmedBalance);
+
+    // Number of transactions in wallet changed
     void numTransactionsChanged(int count);
+
+    // Encryption status of wallet changed
     void encryptionStatusChanged(int status);
+
+    // Signal emitted when wallet needs to be unlocked
+    // It is valid behaviour for listeners to keep the wallet locked after this signal;
+    // this means that the unlocking failed or was cancelled.
     void requireUnlock();
 
     // Asynchronous error notification