editing docs

README.md

@@ -2,11 +2,13 @@
 
 `ripple-lib` connects to the Ripple network via the WebSocket protocol and runs in Node.js as well as in the browser.
 
-This file contains installation and quickstart instructions. For the full documentation see:
+This file contains installation and quickstart instructions. 
+
+For additional documentation see:
 
 1. [The `ripple-lib` Guides](docs/REFERENCE.md)
 2. [The `ripple-lib` API Reference](docs/REFERENCE.md)
-3. Additional documentation resources can be found at:
+3. The Ripple Wiki:
   + https://ripple.com/wiki/Ripple_JavaScript_library  
   + https://ripple.com/wiki  
   + https://ripple.com
@@ -19,7 +21,7 @@ This file contains installation and quickstart instructions. For the full docume
 
 ##Quickstart
 
-`Remote` ([remote.js](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/remote.js)) is the module responsible for managing connections to `rippled` servers.
+`Remote` ([remote.js](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/remote.js)) is the module responsible for managing connections to `rippled` servers:
 
 ```js
 /* Loading ripple-lib with Node.js */
@@ -33,6 +35,7 @@ var remote = new Remote({
   trusted:        true,
   local_signing:  true,
   local_fee:      true,
+  fee_cusion:     1.5,
   servers: [
     {
         host:    's1.ripple.com'
@@ -48,3 +51,5 @@ remote.connect(function() {
   // see the API Reference for available functions
 });
 ```
+
+See [The `ripple-lib` Guides](docs/REFERENCE.md) and [The `ripple-lib` API Reference](docs/REFERENCE.md) for walkthroughs and details about all of the available functions and options.

docs/GUIDES.md

@@ -2,7 +2,7 @@
 
 ###In this document:
 
-1. [Connecting to the Ripple network with the `Remote` module](GUIDES.md#1-connecting-to-the-ripple-network-with-the-remote-module)
+1. [Connecting to the Ripple network with `Remote`](GUIDES.md#1-connecting-to-the-ripple-network-with-remote)
 2. [Using `Remote` functions and `Request` objects](GUIDES.md#2-using-remote-functions-and-request-objects)
 3. [Submitting a transaction](GUIDES.md#3-submitting-a-transaction)
 4. [Listening to the network](GUIDES.md#4-listening-to-the-network)
@@ -13,9 +13,9 @@
 1. [The `ripple-lib` README](../README.md)
 2. [The `ripple-lib` API Reference](REFERENCE.md)
 
-##1. Connecting to the Ripple network with the `Remote` module
-
+##1. Connecting to the Ripple network with `Remote`
 
+Coming Soon
 
 
 ##2. Using `Remote` functions and `Request` objects
@@ -78,4 +78,18 @@ remote.connect(function() {
 });
 ```
 
-##4. Listening to the network
+###A note on transaction fees
+
+A full description of network transaction fees can be found on the [Ripple Wiki](https://ripple.com/wiki/Transaction_Fee).
+
+In short, transaction fees are very small amounts (on the order of ~10) of [XRP drops](https://ripple.com/wiki/Ripple_credits#Notes_on_drops) spent and destroyed with every transaction. They are largely used to account for network load and prevent spam. With `ripple-lib`, transaction fees are calculated locally by default and the fee you are willing to pay is submitted along with your transaction.
+
+Since the fee required for a transaction may change between the time when the original fee was calculated and the time when the transaction is submitted, it is wise to use the [`fee_cushion`](REFERENCE.md#1-remote-options) to ensure that the transaction will go through. For example, suppose the original fee calculated for a transaction was 10 XRP drops but at the instant the transaction is submitted the server is experiencing a higher load and it has raised its minimum fee to 12 XRP drops. Without a `fee_cusion`, this transaction would not be processed by the server, but with a `fee_cusion` of, say, 1.5 it would be processed and you would just pay the 2 extra XRP drops.
+
+The [`max_fee`](REFERENCE.md#1-remote-options) option can be used to avoid submitting a transaction to a server that is charging unreasonably high fees.
+
+
+
+##4. Listening to the network
+
+Coming Soon

docs/REFERENCE.md

@@ -1,5 +1,7 @@
 #`ripple-lib` API Reference
 
+__(More examples coming soon!)__
+
 ###In this document:
 
 1. [`Remote` options](REFERENCE.md#1-remote-options)
@@ -38,8 +40,9 @@ A new `Remote` can be created with the following options:
 + `max_listeners` Set maxListeners for remote; prevents EventEmitter warnings (number)
 + `connection_offset` Connect to remote servers on supplied interval (number in seconds)
 + `trusted` truthy, if remote is trusted (boolean)
-+ `max_fee` Maximum acceptable transaction fee (number in XRP or drops?)
-+ `fee_cushion` Extra fee multiplier to account for async fee changes (?)
++ `local_fee` Set whether the transaction fee range will be set locally (boolean, default is true, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees))
++ `fee_cushion` Extra fee multiplier to account for async fee changes (number, e.g. 1.5, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees))
++ `max_fee` Maximum acceptable transaction fee (number in [XRP drops](https://ripple.com/wiki/Ripple_credits#Notes_on_drops), see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees))
 + `servers` Array of server objects of the following form:
 
 ```js
@@ -238,3 +241,4 @@ Returns a [Transaction](https://github.com/ripple/ripple-lib/blob/develop/src/js
 
 #4. Amount objects
 
+Coming Soon