refactor(array): use extend in add improve docs (#51)

hanxiao · web-flow · commit fca35a0e1f69 · 2022-01-15T17:38:06.000+01:00
diff --git a/docarray/array/document.py b/docarray/array/document.py
@@ -388,12 +388,10 @@ def __bool__(self):
     def __repr__(self):
         return f'<{self.__class__.__name__} (length={len(self)}) at {id(self)}>'
 
-    def __add__(self, other: 'Document'):
+    def __add__(self, other: Union['Document', Sequence['Document']]):
         v = type(self)()
-        for doc in self:
-            v.append(doc)
-        for doc in other:
-            v.append(doc)
+        v.extend(self)
+        v.extend(other)
         return v
 
     def extend(self, values: Iterable['Document']) -> None:
diff --git a/docs/fundamentals/document/serialization.md b/docs/fundamentals/document/serialization.md
@@ -7,6 +7,9 @@ DocArray is designed to be "ready-to-wire": it assumes you always want to send/r
 One should use {ref}`DocumentArray for serializing multiple Documents<docarray-serialization>`, instead of looping over Documents one by one. The former is much faster and yield more compact serialization. 
 ```
 
+```{hint}
+Some readers may wonder: why aren't serialization a part of constructor? They do have similarity. Nonetheless, serialization often contains elements that do not really fit into constructor: input & output model, data schema, compression, extra-dependencies. DocArray made a decision to separate the constructor and serialization for the sake of clarity and maintainability. 
+```
 
 ## From/to JSON
 
diff --git a/docs/fundamentals/documentarray/construct.md b/docs/fundamentals/documentarray/construct.md
@@ -97,6 +97,29 @@ da = DocumentArray(...)
 da1 = DocumentArray(da)
 ```
 
+
+## Construct from multiple DocumentArray
+
+You can use `+` or `+=` to concatenate DocumentArrays together:
+
+```python
+from docarray import DocumentArray
+
+da1 = DocumentArray.empty(3)
+da2 = DocumentArray.empty(4)
+da3 = DocumentArray.empty(5)
+print(da1 + da2 + da3)
+
+da1 += da2
+print(da1)
+```
+
+```text
+<DocumentArray (length=12) at 5024988176>
+<DocumentArray (length=7) at 4525853328>
+```
+
+
 ## Construct from a single Document
 
 ```python
@@ -180,6 +203,7 @@ This will scan all filenames that match the expression and construct Documents w
 
 
 
+
 ## What's next?
 
 In the next chapter, we will see how to construct DocumentArray from binary bytes, JSON, CSV, dataframe, Protobuf message.
diff --git a/docs/fundamentals/documentarray/serialization.md b/docs/fundamentals/documentarray/serialization.md
@@ -12,6 +12,10 @@ DocArray is designed to be "ready-to-wire" at anytime. Serialization is importan
 - Pandas Dataframe: `.from_dataframe()`/`.to_dataframe()`
 - Cloud: `.push()`/`.pull()`
 
+
+
+
+
 ## From/to JSON
 
 
