Update docstrings for as_dataarray and add_variables

Document the coord validation and broadcasting behavior from the
user perspective.

Author: FBumann

linopy/common.py

@@ -273,6 +273,16 @@ def as_dataarray(
     -------
         DataArray:
             The converted DataArray.
+
+    Raises
+    ------
+    ValueError
+        If arr is a DataArray and coords is provided: raised when
+        coordinates for shared dimensions do not match, or when the
+        DataArray has dimensions not covered by coords (unless
+        allow_extra_dims is True). The DataArray's dimensions may be
+        a subset of coords — missing dimensions are added via
+        expand_dims.
     """
     if isinstance(arr, pd.Series | pd.DataFrame):
         arr = pandas_to_dataarray(arr, coords=coords, dims=dims, **kwargs)

linopy/model.py

@@ -449,10 +449,12 @@ def add_variables(
             Upper bound of the variable(s). Ignored if `binary` is True.
             The default is inf.
         coords : list/xarray.Coordinates, optional
-            The coords of the variable array.
-            These are directly passed to the DataArray creation of
-            `lower` and `upper`. For every single combination of
-            coordinates a optimization variable is added to the model.
+            The coords of the variable array. For every single
+            combination of coordinates an optimization variable is
+            added to the model. Data for `lower`, `upper` and `mask`
+            is fitted to these coords: shared dimensions must have
+            matching coordinates, and missing dimensions are broadcast.
+            A ValueError is raised if the data is not compatible.
             The default is None.
         name : str, optional
             Reference name of the added variables. The default None results in
@@ -474,7 +476,9 @@ def add_variables(
         ------
         ValueError
             If neither lower bound and upper bound have coordinates, nor
-            `coords` are directly given.
+            `coords` are directly given. Also raised if `lower` or
+            `upper` are DataArrays whose coordinates do not match the
+            provided `coords`.
 
         Returns
         -------