From e445b6f316926f22f0e308dd3e163c922253bf05 Mon Sep 17 00:00:00 2001
From: Yu Wei Wu <wusyong9104@gmail.com>
Date: Tue, 27 Nov 2018 12:53:37 +0800
Subject: [PATCH] Add documentation for more extended api

---
 docs/api.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 iota/api.py  | 13 +++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index f0af315..1a9c176 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -204,6 +204,34 @@ This method returns a ``dict`` with the following items:
 -  ``bundles: List[Bundle]``: Matching bundles, sorted by tail
    transaction timestamp.
 
+``is_reattachable``
+-------------------
+
+This API function helps you to determine whether you should replay a
+transaction or make a new one (either with the same input, or a
+different one).
+
+This method takes one or more input addresses (i.e. from spent
+transactions) as input and then checks whether any transactions with a
+value transferred are confirmed.
+
+If yes, it means that this input address has already been successfully
+used in a different transaction, and as such you should no longer replay
+the transaction.
+
+Parameters
+~~~~~~~~~~
+
+- ``address: Iterable[Address]``: List of addresses.
+
+Return
+~~~~~~
+
+This method returns a ``dict`` with the following items:
+
+- ``reattachable: List[Bool]``: Always a list, even if only one address
+  was queried.
+
 ``prepare_transfer``
 --------------------
 
@@ -232,6 +260,24 @@ This method returns a ``dict`` with the following items:
 -  ``trytes: List[TransactionTrytes]``: Raw trytes for the transactions
    in the bundle, ready to be provided to ``send_trytes``.
 
+``promote_transaction``
+-----------------------
+
+Promotes a transaction by adding spam on top of it.
+
+-  ``transaction: TransactionHash``: Transaction hash. Must be a tail.
+-  ``depth: int``: Depth at which to attach the bundle.
+-  ``min_weight_magnitude: Optional[int]``: Min weight magnitude, used
+   by the node to calibrate Proof of Work.
+-  If not provided, a default value will be used.
+
+Return
+~~~~~~
+
+This method returns a ``dict`` with the following items:
+
+-  ``bundle: Bundle``: The newly-published bundle.
+
 ``replay_bundle``
 -----------------
 
diff --git a/iota/api.py b/iota/api.py
index f6ce7d7..518bf5e 100644
--- a/iota/api.py
+++ b/iota/api.py
@@ -907,6 +907,19 @@ def promote_transaction(
         """
         Promotes a transaction by adding spam on top of it.
 
+        :param transaction:
+            Transaction hash.  Must be a tail transaction.
+
+        :param depth:
+            Depth at which to attach the bundle.
+            Defaults to 3.
+
+        :param min_weight_magnitude:
+            Min weight magnitude, used by the node to calibrate Proof of
+            Work.
+
+            If not provided, a default value will be used.
+
         :return:
             Dict with the following structure::