DOC: Reindexing behaviour of dataframe column-assignment missing

pandas/core/indexing.py

@@ -287,6 +287,10 @@ def loc(self) -> _LocIndexer:
         - An alignable boolean Series. The index of the key will be aligned before
           masking.
         - An alignable Index. The Index of the returned selection will be the input.
+
+          .. warning:: Preferred syntax to assign a column: `df[]` instead of
+              allocation through `df.loc[]`
+
         - A ``callable`` function with one argument (the calling Series or
           DataFrame) and that returns valid output for indexing (one of the above)
 
@@ -388,6 +392,9 @@ def loc(self) -> _LocIndexer:
 
         **Setting values**
 
+          .. warning:: Preferred syntax to assign a column: `df['shield']`
+             instead of allocation through `df.loc[]` such as `df.loc['shield']`
+
         Set value for all items matching the list of labels
 
         >>> df.loc[['viper', 'sidewinder'], ['shield']] = 50
@@ -445,6 +452,36 @@ def loc(self) -> _LocIndexer:
         8          4       5
         9          7       8
 
+        **Setting values using Series**
+
+        Assign column using Series
+
+        >>> 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