From 511176648324f7cce610b1a2ed3d7f9b33cb7f54 Mon Sep 17 00:00:00 2001
From: Evgeniy Blinov <zheni-b@yandex.ru>
Date: Wed, 7 Aug 2024 01:30:51 +0300
Subject: [PATCH] documentation for new adding optimizations

---
 docs/types_of_tokens/SimpleToken.md |  9 ---------
 docs/what_are_tokens/summation.md   | 30 ++++++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/docs/types_of_tokens/SimpleToken.md b/docs/types_of_tokens/SimpleToken.md
index 8e43abb..6e8f9da 100644
--- a/docs/types_of_tokens/SimpleToken.md
+++ b/docs/types_of_tokens/SimpleToken.md
@@ -9,13 +9,4 @@ token.cancel()
 print(token.cancelled)  #> True
 ```
 
-`SimpleToken` is also implicitly generated by the operation of summing two other tokens:
-
-```python
-from cantok import CounterToken, TimeoutToken
-
-print(repr(CounterToken(5) + TimeoutToken(5)))
-#> SimpleToken(CounterToken(5, direct=True), TimeoutToken(5))
-```
-
 There is not much more to tell about it if you have read [the story](../what_are_tokens/in_general.md) about tokens in general.
diff --git a/docs/what_are_tokens/summation.md b/docs/what_are_tokens/summation.md
index fa4600e..5e8c317 100644
--- a/docs/what_are_tokens/summation.md
+++ b/docs/what_are_tokens/summation.md
@@ -1,10 +1,10 @@
-Any tokens can be summed up among themselves. The summation operation generates another [`SimpleToken`](../types_of_tokens/SimpleToken.md) that includes the previous 2:
+Tokens can be summed using the operator `+`:
 
 ```python
-from cantok import SimpleToken, TimeoutToken
-
-print(repr(SimpleToken() + TimeoutToken(5)))
-#> SimpleToken(TimeoutToken(5))
+first_token = TimeoutToken(5)
+second_token = ConditionToken(lambda: True)
+print(repr(first_token + second_token))
+#> SimpleToken(TimeoutToken(5), ConditionToken(λ))
 ```
 
 This feature is convenient to use if your function has received a token with certain restrictions and wants to throw it into other called functions, imposing additional restrictions:
@@ -17,3 +17,23 @@ def function(token: AbstractToken):
   another_function(token + TimeoutToken(5))  # Imposes an additional restriction on the function being called: work for no more than 5 seconds. At the same time, it does not know anything about what restrictions were imposed earlier.
   ...
 ```
+
+The token summation operation always generates a new token. If at least one of the operand tokens is canceled, the sum will also be canceled. It is also guaranteed that the cancellation of this token does not lead to the cancellation of operands. That is, the sum of two tokens always behaves as if it were a [`SimpleToken`](../types_of_tokens/SimpleToken.md) in which both operands were [nested](embedding.md). However, it is difficult to say exactly which token will result from summation, since the library strives to minimize the generated graph of tokens for the sake of performance.
+
+You may notice that some tokens disappear altogether during summation:
+
+```python
+print(repr(SimpleToken() + TimeoutToken(5)))
+#> TimeoutToken(5)
+print(repr(SimpleToken(cancelled=True) + TimeoutToken(5)))
+#> SimpleToken(cancelled=True)
+```
+
+In addition, you can not be afraid to sum more than 2 tokens - this does not generate anything superfluous:
+
+```python
+print(repr(TimeoutToken(5) + ConditionToken(lambda: False) + CounterToken(23)))
+#> TimeoutToken(5, ConditionToken(λ), CounterToken(23))
+```
+
+In fact, there are quite a few effective ways to optimize the token addition operation that are implemented in the library. This operation is pretty well optimized, so it is recommended in all cases when you need to combine the constraints of different tokens in one.