Since we are introducing Array API compatibility we are discussing that some functions (especially in the metrics section) would not return the input array type, but a numpy array.

How would we document that, so that users know what they get as a return type?

We have started to discuss this here, here and here (and possibly in other places), but this discussion a bit scattered and in this issue I am trying to bring this together.

I would think we need to find a standard way of how to talk about return types in the docstrings.

• use the terms ndarray and array (or something more eye-catching) for the input array type
• from the docstring, link to a dedicated section in the glossary, explaining the differences between ndarray and array and which are the implications for the users

What are the general feelings about that?
@ogrisel @OmarManzoor @adrinjalali (I don't want to bother you by tagging, but it would be interesting to hear the takes of betatim, thomasjpfan, lesteve and jeremiedbb as well if they are interested 😅)