DOC: Reindexing behaviour of dataframe column-assignment missing

pandas/core/indexing.py

@@ -443,6 +443,40 @@ def loc(self) -> _LocIndexer:
         8          4       5
         9          7       8
 
+        **Setting values using Series**
+
+        Assign column using Series
+
+        .. warning::
+        Preferred syntax to assign a column: `df['shield']` instead
+        of allocation through `df.loc[]`
+
+        >>> df.loc[:, 'shield'] = pd.Series({7: 8, 8: 10, 9: 13})
+        >>> df
+           max_speed  shield
+        7          1       8
+        8          4      10
+        9          7      13
+
+        Assigning column to a Series with non matching indexes aligns the
+        right hand side to the index of the left
+
+        >>> df.loc[:, 'shield'] = pd.Series({8: 10})
+        >>> df
+           max_speed  shield
+        7          1     NaN
+        8          4    10.0
+        9          7     NaN
+
+        Assign column containing value with missing index
+
+        >>> df.loc[:, 'shield'] = pd.Series({11: 14})
+        >>> df
+           max_speed  shield
+        7          1     NaN
+        8          4     NaN
+        9          7     NaN
+
         **Getting values with a MultiIndex**
 
         A number of examples using a DataFrame with a MultiIndex