Updated Herald API (markdown)

Herald-API.md

@@ -50,13 +50,13 @@ Responses are similar:
 
 **Subscriptions**
 ------
-These 
-- `blockchain.address.subscribe`
+The following APIs are for subscriptions:
+- `blockchain.address.subscribe` notifies whenever an address is touched, ie it received a new tx or one of its txs has been spent -  in mempool or in a new block.
 - `blockchain.address.unsubscribe`
 - `blockchain.scripthash.subscribe`
 - `blockchain.scripthash.unsubscribe`
-- `blockchain.headers.subscribe`
-- `server.peers.subscribe`
+- `blockchain.headers.subscribe` notifies with new block headers as new blocks are found
+- `server.peers.subscribe` notifies when the hub peers (federated hubs) changes
 
 
 **Methods**