DOC: Docstring updates

Author: kernc

backtesting/backtesting.py

@@ -87,7 +87,7 @@ def I(self,  # noqa: E743
         `backtesting.backtesting.Strategy.data` is.
         Returns `np.ndarray` of indicator values.
 
-        `func` is a function that returns the indicator array of
+        `func` is a function that returns the indicator array(s) of
         same length as `backtesting.backtesting.Strategy.data`.
 
         In the plot legend, the indicator is labeled with
@@ -245,12 +245,12 @@ def data(self) -> _Data:
         return self._data
 
     @property
-    def position(self):
+    def position(self) -> 'Position':
         """Instance of `backtesting.backtesting.Position`."""
         return self._broker.position
 
     @property
-    def orders(self):
+    def orders(self) -> 'Orders':
         """Instance of `backtesting.backtesting.Orders`."""
         return self._broker.orders
 
@@ -459,11 +459,11 @@ def __repr__(self):
         return '<Broker: {:.0f}{:+.1f}>'.format(self._cash, self.position.pl)
 
     def buy(self, price=None, sl=None, tp=None):
-        assert (sl or -np.inf) <= (price or self.last_close) <= (tp or np.inf), (sl, price or self.last_close, tp)  # noqa: E501
+        assert (sl or -np.inf) <= (price or self.last_close) <= (tp or np.inf), "For long orders should be: SL ({}) < BUY PRICE ({}) < TP ({})".format(sl, price or self.last_close, tp)  # noqa: E501
         self.orders._update(price, sl, tp)
 
     def sell(self, price=None, sl=None, tp=None):
-        assert (tp or -np.inf) <= (price or self.last_close) <= (sl or np.inf), (tp, price or self.last_close, sl)  # noqa: E501
+        assert (tp or -np.inf) <= (price or self.last_close) <= (sl or np.inf), "For short orders should be: TP ({}) < BUY PRICE ({}) < SL ({})".format(tp, price or self.last_close, sl)  # noqa: E501
         self.orders._update(price, sl, tp, is_long=False)
 
     def close(self):
@@ -602,20 +602,20 @@ def __init__(self,
         or a monotonic range index (i.e. a sequence of periods).
 
         `strategy` is a `backtesting.backtesting.Strategy`
-        _subclass_ (not instance).
+        _subclass_ (not an instance).
 
         `cash` is the initial cash to start with.
 
         `commission` is the commision ratio. E.g. if your broker's commission
         is 1% of trade value, set commission to `0.01`. Note, if you wish to
-        account for bid-ask spread, you approximate doing so by increasing
+        account for bid-ask spread, you cam approximate doing so by increasing
         the commission, e.g. set it to `0.0002` for commission-less forex
-        trading where average spread is roughly 0.2‰ of asking price.
+        trading where the average spread is roughly 0.2‰ of asking price.
 
         `margin` is the required margin (ratio) of a leveraged account.
         No difference is made between initial and maintenance margins.
-        To run the backtest using e.g. 50:1 leverge your broker allows,
-        set margin to `0.02`.
+        To run the backtest using e.g. 50:1 leverge that your broker allows,
+        set margin to `0.02` (1 / leverage).
 
         If `trade_on_close` is `True`, market orders will be executed
         with respect to the current bar's closing price instead of the
@@ -736,7 +736,8 @@ def optimize(self,
         If `return_heatmap` is `True`, besides returning the result
         series, an additional `pd.Series` is returned with a multiindex
         of all admissible parameter combinations, which can be further
-        inspected or projected onto 2D to plot a heatmap.
+        inspected or projected onto 2D to plot a heatmap
+        (see `backtesting.backtesting.lib.plot_heatmaps()`).
 
         Additional keyword arguments represent strategy arguments with
         list-like collections of possible values. For example, the following