improve documentation

backend-transaction/src/main/java/de/cotto/bitbook/backend/transaction/TransactionService.java

@@ -20,7 +20,7 @@
 public class TransactionService {
     /**
      * Only persist information about transactions that are that many blocks deep,
-     * so that chain reorgs do not invalidate persisted data.
+     * so that chain reorganization do not invalidate persisted data.
      */
     private static final int CONFIRMATION_LIMIT = 6;
 
@@ -107,7 +107,7 @@ private boolean hasInsufficientConfirmationDepth(Transaction transaction) {
             // unconfirmed transaction, in mempool
             return true;
         }
-        // too recent, may get lost in chain reorg
+        // too recent, may get lost in chain reorganization
         return blockHeight > getChainBlockHeight() - CONFIRMATION_LIMIT;
     }
 

documentation/commands.md

@@ -10,7 +10,7 @@ The output includes the block height of the block that includes the transaction,
 when this transaction was first seen (which may be identical to the time the block was mined).
 
 The fiat value shown next to the coin amount is based on the exchange rate at the time shown above.
-The fiat exchange rate is only requested once per day, which is why the shown value may not be precise.
+The fiat exchange rate is only requested once per day, which is why the shown value may be imprecise.
 
 The inputs and outputs are aggregated per address.
 The symbol to the right of the address shows the ownership status (`?` if not set).
@@ -30,7 +30,7 @@ Outputs:
 ```
 
 Note that BitBook only shows confirmed transactions with a confirmation depth of at least 6 confirmations.
-This is done to avoid having outdated information in the case of chain reorgs.
+This is done to avoid having outdated information in the case of chain reorganizations.
 
 ## Get Address Transactions
 Using the `get-address-transactions` command you get information about all transactions connected to the address:
@@ -96,7 +96,7 @@ You can reset ownership information for an address using `reset-ownership <addre
 
 ### List Owned Addresses
 The command `list-owned-addresses` can be used to list the addresses you marked as `owned`.
-The output includes the current balance with the current fiat value, and the addresses descriptions (if set).
+The output includes the current balance with the current fiat value, and the addresses' descriptions (if set).
 The output is sorted by value, so that the addresses with the highest number of coins are shown at the bottom of the
 list.
 
@@ -178,8 +178,8 @@ f74b5dd425497eaabbee8562cf9b41b1f99ba7209d199ca0ac9c0aee4b4804c5:   -0.1238648
 ```
 
 The command output is a list of transactions, similar to what you see in [Get Address Transactions](#get-address-transactions).
-The coin amount indicates the change from/to unknown addresses caused by the transaction, where zero values are not
-included in the output.
+The coin amount indicates the change from/to unknown addresses caused by the transaction, where transactions with
+a value of zero are not included in the output.
 
 This information is aggregated over all of your owned addresses, so that transactions between your owned addresses do
 not show up (fees are considered to be sent to a foreign address).
@@ -189,7 +189,7 @@ are shown at the bottom.
 
 **As described in the [example](example.md), you could go through the list of
 transactions (using [Get Transaction Details](#get-transaction-details)) and add ownership information until the
-returned list ist empty.**
+returned list is empty.**
 
 The fiat value shown next to the coin amount is based on the exchange rate at the day of the corresponding transaction.
 Descriptions set for transactions are included in the output.
@@ -201,23 +201,28 @@ cause a delay (see [Get Address Transactions](#get-address-transactions)).
 You can set textual descriptions to addresses and transactions so that this additional information is shown in the
 commands' outputs in addition to the address/transaction hash.
 
+**Note that you have to use quotes (`"` or `'`) if the description includes a space!**
+
 ```
 BitBook$ set-address-description 1ET8va8cJNGGLtG7pwRq79EeE7qNb7ofCS "Pete Peterson"
 OK
-set-transaction-description f74b5dd425497eaabbee8562cf9b41b1f99ba7209d199ca0ac9c0aee4b4804c5 "Stuff from Pete"
+BitBook$ set-transaction-description f74b5dd425497eaabbee8562cf9b41b1f99ba7209d199ca0ac9c0aee4b4804c5 "Stuff from Pete"
+OK
 ```
 
 You can also remove descriptions using `remove-address-description` and `remove-transaction-description`.
 
 ## Tab Completion
 All commands taking address or transaction hashes as arguments support tab completion.
-For addresses, completion works for addresses that are either "known" (by, possibly indirectly,
-using `get-address-transactions`), or if the address is listed as an input or output of a known transaction.
+For addresses, completion works for addresses that are either "known" (for example, because the details have been
+received using `get-address-transactions`), or if the address is listed as an input or output of a known transaction.
 
-For transactions the hashes are completed for known transactions (`get-transaction-details`), and for hashes associated
-with an address (`get-address-transactions`).
+Transaction hashes are completed for known transactions (for example, received using `get-transaction-details`), and
+for hashes associated with an address (for example, because it is listed in the output of a `get-address-transactions`
+invocation).
 
 As such, if you see an address/transaction on screen, you can always complete it using tab completion.
+You may also use copy-paste. Invalid characters (like `:` or spaces) are automatically ignored.
 
 In addition to this, you can also use the description to complete the command:
 

documentation/example.md

@@ -194,7 +194,8 @@ OK
 Similary, you can also set a description for a transaction:
 
 ```
-set-transaction-description f74b5dd425497eaabbee8562cf9b41b1f99ba7209d199ca0ac9c0aee4b4804c5 "Stuff from Pete"
+BitBook$ set-transaction-description f74b5dd425497eaabbee8562cf9b41b1f99ba7209d199ca0ac9c0aee4b4804c5 "Stuff from Pete"
+OK
 ```
 
 This information is then included whenever the transaction hash is shown:

documentation/limitations.md

@@ -24,4 +24,4 @@ Also see [issue #5](https://github.com/C-Otto/BitBook/issues/5).
 
 ## Pagination
 For addresses for which many transaction hashes are known, BitBook currently is unable to use most API's responses.
-This implementation details is addressed in [issue #6](https://github.com/C-Otto/BitBook/issues/6).
+This implementation detail is addressed in [issue #6](https://github.com/C-Otto/BitBook/issues/6).

documentation/technical.md

@@ -3,7 +3,7 @@ In addition to tracking my coins, I started this project to experiment with seve
 tools and techniques. As such, BitBook is based on recent versions of Java and Gradle,
 and incorporates several tools like Errorprone that aren't strictly necessary.
 
-I appreciate constructive criticisms about the choice of frameworks, implementation 
+I appreciate constructive criticism about the choice of frameworks, implementation 
 details, and just about anything else. **Please help me learn and improve!
 Please create issues, provide pull requests, send mails, reach out via Twitter, ...!**
 
@@ -33,8 +33,8 @@ there's quite a lot of code that helps accomplish this.
 #### APIs and Providers
 A provider is responsible to provide the requested information, which usually means sending HTTP (REST) requests to
 some API and returning the parsed responses as Java objects.
-We use Feign to implement the actual HTTP clients, and Jackson for deserialization.
-Additionally, we use resilience4j to add circuit-breakers and rate-limiters.
+BitBook uses Feign to implement the actual HTTP clients, and Jackson for deserialization.
+Additionally, BitBook uses resilience4j to add circuit-breakers and rate-limiters.
 
 Currently, the following providers are implemented:
 ```
@@ -63,11 +63,12 @@ providers (APIs) based on their recent performance/failure rates.
 
 Most "visible" requests also cause "invisible" requests that are served in the background (using the 'lowest' priority).
 The results are persisted in the database, so that future requests can be served much faster.
-As an example, when requesting details about a transaction, the price at time of the transaction is requested in the
+As an example, when requesting details about a transaction, the price at the time of the transaction is requested in the
 background.
 
 The request classes make use of `CompletableFuture` and `Consumer<R>` to forward request results to the code that
-requested the information (to show it to the user) or should do something with it (persist results to database).
+requested the information. This is necessary so that the results can be shown to the user, or so that follow-up
+operations (persisting to database, requesting more information) can be triggered.
 
 As there may be several requests for the same piece of information (which may be merged/re-used/...), the code
 responsible for the queue organization and result forwarding is rather complex.
@@ -81,7 +82,7 @@ As an example, I'm unable to use case-insensitive tab completion (see [issue #20
 
 Furthermore, tab completion only works if the completion suggestion contains the phrase in front of `<tab>`, i.e.
 `foo<tab>` will only show suggestions that include `foo`. In order to make tab completion work for descriptions,
-I had to resort to a weird hack involving a null byte seperator (see `AbstractCompletionProvider`).
+I had to resort to a weird hack involving a null byte separator (see `AbstractCompletionProvider`).
 Note that this is also the case if the phrase (`foo`) is included in the description of the completion suggestion.
 
-I'd also like to end the program using CTRL+D, which doesn't seem to be possible.
+I'd also like to be able to end the program using CTRL+D, which doesn't seem to be possible.