fixed doc that still referenced some old class names and attributes.

README.adoc

@@ -27,8 +27,7 @@ image:https://sonarcloud.io/api/project_badges/measure?project=neurallayer_roboq
 image:https://sonarcloud.io/api/project_badges/measure?project=neurallayer_roboquant&metric=sqale_rating[Maintainability Rating, link=https://sonarcloud.io/component_measures?id=neurallayer_roboquant&metric=new_maintainability_rating&view=list]
 
 
-
-_Roboquant_ is an algorithmic trading platform that is lightning fast and flexible while at the same time strives to be developer friendly. It is fully open source, written in Kotlin, and can be used in Jupyter Notebooks as well as standalone applications.
+_Roboquant_ is an algorithmic trading platform that is fast and flexible while at the same time strives to be developer friendly. It is fully open source, written in Kotlin, and can be used in Jupyter Notebooks as well as standalone applications.
 
 It is designed to be used by anyone serious about algo trading, from beginning retail traders to established trading firms. You can find out more at *https://roboquant.org[roboquant.org]*.
 
@@ -45,9 +44,9 @@ val account = run(feed, strategy) // <3>
 println(account) // <4>
 ----
 <1> Create the strategy that you want to validate
-<2> What data should be used, in this case, CSV files
+<2> What data should be used, in this case, a directory with CSV files
 <3> Run the back test
-<4> Print the account at the end of the run
+<4> Print the account state at the end of the run
 
 You can find out more at the online https://roboquant.org/tutorial/index.html[tutorial^].
 
@@ -124,7 +123,7 @@ Some key features of _roboquant_ are:
 * [x] Developed under open source with a permissive Apache license
 * [x] Use Jupyter Notebooks with insightful charts if you prefer interactive development
 * [x] Batteries included, for example, 150+ technical indicators and ready to use datasets
-* [x] Out of the box integration with Alpaca, Interactive Brokers, Alpha Vantage, Polygon, ECB, Binance and most other crypto exchanges
+* [x] Out of the box integration with Alpaca, Interactive Brokers and the ECB, and many CSV data providers.
 
 See also https://roboquant.org/background/features.html[Features] for a more extensive feature list and how roboquant compares to some other platforms.
 

roboquant/src/main/kotlin/org/roboquant/brokers/Account.kt

@@ -31,8 +31,8 @@ import java.time.Instant
  * - The [orders]
  *
  * Some convenience methods convert a multi-currency Wallet to a single-currency Amount.
- * For this to work, you'll
- * need to have the appropriate exchange rates defined at [Config.exchangeRates].
+ * For this to work, you'll need to have the appropriate exchange rates defined
+ * at [Config.exchangeRates].
  *
  * @property baseCurrency the base currency of the account
  * @property lastUpdate time that the account was last updated
@@ -64,13 +64,13 @@ interface Account {
     fun equityAmount(): Amount = convert(equity())
 
     /**
-     * Total equity hold in the account.
+     * Calculate the total equity hold in the account and return the result as a [Wallet]
      * Equity is defined as the sum of [cash] balances and the market value of the open [positions].
      */
     fun equity(): Wallet = cash + marketValue()
 
     /**
-     * Unique set of assets hold in the open [positions]
+     * The unique set of assets hold in the open [positions]
      */
     val assets: Set<Asset>
         get() = positions.keys
@@ -83,12 +83,14 @@ interface Account {
     }
 
     /**
-     * Return the position size for the provided asset
+     * Return the position size for the provided asset within this account. If there is no open position,
+     * a size of ZERO is returned.
      */
     fun positionSize(asset: Asset) : Size = positions[asset]?.size ?: Size.ZERO
 
     /**
-     * Return the unrealized PNL of the open positions, optionally filter by one or more asset.
+     * Return the unrealized PNL of the open positions, optionally filter by one or more asset. If there is
+     * not match, an empty [Wallet] will be returned.
      */
     fun unrealizedPNL(vararg assets: Asset): Wallet {
         return positions.filterValues { assets.isEmpty() || it.asset in assets }.values.unrealizedPNL

roboquant/src/main/kotlin/org/roboquant/brokers/Broker.kt

@@ -39,6 +39,9 @@ interface Broker {
 
     /**
      * Place new [instructions] at this broker.
+     *
+     * Typically, this method will invoke the underlying broker API to place the orders and set the corresponding order-id.
+     * Place orders can also be used to update or cancel orders.
      */
     fun placeOrders(instructions: List<Instruction>)
 

roboquant/src/main/kotlin/org/roboquant/common/Amount.kt

@@ -27,7 +27,7 @@ import kotlin.math.absoluteValue
  * An amount holds the monetary [value] for a single [currency].
  *
  * For storing monetary amounts internally it uses [Double], since it is accurate enough for trading while providing
- * large performance benefits over BigDecimal.
+ * performance benefits over types like BigDecimal.
  *
  * @property currency the currency of the amount
  * @property value the value of the amount

roboquant/src/main/kotlin/org/roboquant/common/Logging.kt

@@ -21,9 +21,7 @@ import kotlin.reflect.KClass
 
 /**
  * Simple Logging object that provides utility methods to create loggers and supports lazy logging
- *
- * Please note this is a logger that is used in Kotlin source code, not to be confused with a MetricsLogger
- * that can be used to log metrics during a run.
+ * It is an implementation of [org.slf4j.Logger].
  */
 object Logging {
 

roboquant/src/main/kotlin/org/roboquant/common/Size.kt

@@ -23,7 +23,7 @@ import kotlin.math.sign
 
 /**
  * Represents the size of orders, positions and trades. This implementation is precise up to 8 decimals, ensuring that
- * order and position sizes are accurate enough when dealing with fractional orders.
+ * order and position sizes are accurate enough when dealing with most fractional orders.
  *
  * Since this implementation is a value class, there is no overhead compared to a Double or Long.
  */

roboquant/src/main/kotlin/org/roboquant/common/Timeframe.kt

@@ -103,7 +103,7 @@ data class Timeframe(val start: Instant, val end: Instant, val inclusive: Boolea
         /**
          * The empty timeframe doesn't contain any time.
          */
-        val EMPTY = Timeframe(MIN, MIN)
+        val EMPTY = Timeframe(MIN, MIN, false)
 
         // Different formatters used when displaying a timeframe
         private val dayFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd")

roboquant/src/main/kotlin/org/roboquant/feeds/Event.kt

@@ -21,7 +21,8 @@ import org.roboquant.common.Timeframe
 import java.time.Instant
 
 /**
- * An event contains a list of [items] that all happened at the same moment in [time].
+ * An event contains a list of [items] that all happened at the same moment in [time]. An [Item] can be anything, but a
+ * common use case is price items like candlesticks.
  *
  * @property items the list of actions that are part of this event
  * @property time the time that the actions in this event became available

roboquant/src/main/kotlin/org/roboquant/feeds/Item.kt

@@ -23,18 +23,17 @@ import org.roboquant.feeds.OrderBook.OrderBookEntry
 import kotlin.math.absoluteValue
 
 /**
- * An action is the lowest level of information contained in an [Event] and can be anything from a price action for an
+ * An item is the lowest level of information contained in an [Event] and can be anything from a market price for an
  * asset to an annual report or a Twitter tweet.
- * An action doesn't have to be linked to a particular asset, although [PriceItem]s are.
+ * An item doesn't have to be linked to a particular asset, although [PriceItem]s are.
  *
- * The content of the action is determined by the class implementing this interface. Strategies are expected to filter
- * on those types of actions they are interested in.
+ * The content of the item is determined by the class implementing this interface. Strategies are expected to filter
+ * on those types of items they are interested in.
  *
  * # Example
  * ```
  * event.actions.filterIsInstance<PriceBar>(). ...
  * ```
- *
  */
 interface Item
 

roboquant/src/main/kotlin/org/roboquant/journals/BasicJournal.kt

@@ -7,7 +7,8 @@ import java.time.Instant
 import kotlin.math.max
 
 /**
- * Tracks basic progress metrics and optionally print them to the console
+ * Tracks basic progress metrics and optionally print them to the console. This journal has very low overhead and provides
+ * basic insights into what is happening.
  */
 class BasicJournal(private val printToConsole: Boolean = false) : Journal {
 

roboquant/src/main/kotlin/org/roboquant/journals/Journal.kt

@@ -10,7 +10,9 @@ import org.roboquant.orders.Instruction
 interface Journal {
 
     /**
-     * track the progress of a particular run
+     * Track the progress of a particular run. This method is invoked at each step during a run.
+     *
+     * The passed instructions are only those instructions that were generated during this step.
      */
     fun track(event: Event, account: Account, instructions: List<Instruction>)
 

roboquant/src/main/kotlin/org/roboquant/journals/MemoryJournal.kt

@@ -8,6 +8,9 @@ import org.roboquant.orders.Instruction
 import java.time.Instant
 import java.util.*
 
+/**
+ * Base interface for journals that can be configured using metrics.
+ */
 interface MetricsJournal: Journal {
 
     /**

roboquant/src/main/kotlin/org/roboquant/orders/Cancellation.kt

@@ -17,9 +17,9 @@
 package org.roboquant.orders
 
 /**
- * Cancel an open create-order.
+ * Cancel an existing order.
  *
- * @param orderId the id of the order to cancel
+ * @param orderId the id of the order to cancel, this is required.
  * @param tag an optional tag
  */
 class Cancellation(

roboquant/src/main/kotlin/org/roboquant/orders/Order.kt

@@ -8,7 +8,7 @@ import java.time.Instant
  * Base class for all types of create orders. This ranges from a simple [MarketOrder], all the way to advanced order
  * types like a [BracketOrder].
  *
- * The only hting they all have in common is they refer to a single [asset] and can optionally have a tag associated with them.
+ * The only thing they all have in common is they refer to a single [asset] and can optionally have a tag associated with them.
  */
 abstract class Order(val asset: Asset, val tag: String="") : Instruction() {
 

roboquant/src/main/kotlin/org/roboquant/run.kt

@@ -35,7 +35,10 @@ import kotlin.math.roundToInt
 
 
 /**
- * Blocking version of runAsync
+ * Start a run, this can be used with historical data as well as live data. At least a [Feed] and [Strategy] should be
+ * provider, other parameters have defaults.
+ *
+ * This is the blocking version of runAsync. If you want to have many runs in parallel, use the async version.
  */
 fun run(
     feed: Feed,

roboquant/src/main/kotlin/org/roboquant/strategies/ParallelStrategy.kt

@@ -20,7 +20,7 @@ import kotlinx.coroutines.*
 import org.roboquant.feeds.Event
 
 /**
- * SignalStrategy that runs a number of other strategies in parallel and combines the result. The strategies will each run
+ * This Strategy that runs a number of other strategies in parallel and combines the result. The strategies will each run
  * in their own coroutine, and the results are aggregated after they are finished. The order of aggregation is the same
  * as the order of strategies that is provided in the constructor.
  *

roboquant/src/main/kotlin/org/roboquant/strategies/Signal.kt

@@ -23,7 +23,8 @@ import org.roboquant.strategies.SignalType.*
  * This enum class represents the type of signal: [ENTRY], [EXIT] or [BOTH] and can be used by more advanced
  * strategies that provide different signals for entering and exiting a position.
  *
- * Please note it is up to the signalConverter to use this additional information and simple implementations might ignore it.
+ * Please note it is up to the [org.roboquant.traders.Trader] to use this additional information and
+ * simple implementations might ignore it.
  */
 enum class SignalType {
 

roboquant/src/main/kotlin/org/roboquant/strategies/Strategy.kt

@@ -21,7 +21,7 @@ import org.roboquant.feeds.Event
 
 /**
  * The Strategy is the interface that any trading strategy will need to implement. A strategy receives an
- * [Event] and [Account] and can generate zero or more Instructions/Orders.
+ * [Event] and can generate zero or more Signals.
  *
  * Roboquant makes no assumptions on the type of strategy. It can range from a technical indicator all the way
  * to sentiment analysis using machine learning.

roboquant/src/main/kotlin/org/roboquant/traders/FlexTrader.kt

@@ -53,8 +53,11 @@ open class FlexPolicyConfig(
 )
 
 /**
- * This is the default trader that will be used if no other trader is specified.
- * There are several properties that can be specified during construction that change the underlying behavior:
+ * This is the default trader that will be used if no other trader is specified. It includes some common behavior that
+ * is typically required when bringing a solution live.
+ *
+ * There are several properties that can be specified during construction that change the underlying behavior by defining
+ * a [FlexPolicyConfig].
  *
  * ```
  * val trader = FlexTrader {

roboquant/src/main/kotlin/org/roboquant/traders/Trader.kt

@@ -23,7 +23,7 @@ import org.roboquant.strategies.Signal
 
 /**
  * A trader is responsible for creating [Orders][Instruction], typically based on the [Signals][Signal] generated by a
- * strategy. Besides, turning signals into orders, a trader should also take care of:
+ * strategy. Besides, turning signals into orders, a trader could also take care of:
  *
  * * signal conflicts: for example, receive both a SELL and BUY signal for the same asset at the same time
  * * order management: for example, how to deal with open orders
@@ -36,12 +36,12 @@ import org.roboquant.strategies.Signal
 interface Trader  {
 
     /**
-     * Based on the received [signals], the latest state of the [account] and the last known [event] to create zero or
+     * Based on the received [signals], the latest state of the [account] and the last known [event], create zero or
      * more orders.
      *
      * @param signals the list of [signals][Signal] generated by the strategy
      * @param account the account state at a point in time
-     * @param event the market data
+     * @param event the data available
      * @return a list of orders
      */
     fun createOrders(signals: List<Signal>, account: Account, event: Event): List<Instruction>