map_over_datasets - What is the required output of func?

[Illviljan]

What is your issue?

The introductory text and type hints seems to match:

xarray/xarray/core/datatree_mapping.py

Line 45 in 4bbab48

func: Callable[..., Dataset | None | tuple[Dataset | None, ...]],

xarray/xarray/core/datatree_mapping.py

Lines 58 to 62 in 4bbab48

	``func`` needs to return a Dataset, tuple of Dataset objects or None in order
	to be able to rebuild the subtrees after mapping, as each result will be
	assigned to its respective node of a new tree via `DataTree.from_dict`. Any
	returned value that is one of these types will be stacked into a separate
	tree before returning all of them.

But the parameter doc is more restrictive:

xarray/xarray/core/datatree_mapping.py

Lines 75 to 80 in 4bbab48

	func : callable
	Function to apply to datasets with signature:
	`func(*args: Dataset, **kwargs) -> Union[Dataset, tuple[Dataset, ...]]`.
	(i.e. func must accept at least one Dataset and return at least one Dataset.)

Some examples showing the different return types would be nice as well. I understand the use case of func: Callable[..., Dataset], but I struggle with the other return types.