ObservablesArray docstring improvement

qiskit/primitives/containers/observables_array.py

@@ -98,7 +98,24 @@ def __repr__(self):
         return prefix + array + suffix
 
     def tolist(self) -> list:
-        """Convert to a nested list"""
+        """Convert to a nested list.
+
+        Similar to Numpy's `tolist` method, the level of nesting
+        depends on the dimension of the observables array. In the
+        case of dimension 0 the method returns a single observable
+        instead of a list.
+
+        Examples::
+            Return values for a one-element list vs one element:
+
+                >>> from qiskit.primitives.containers.observables_array import ObservablesArray
+                >>> oa = ObservablesArray.coerce(["Z"])
+                >>> print(type(oa.tolist()))
+                <class 'list'>
+                >>> oa = ObservablesArray.coerce("Z")
+                >>> print(type(oa.tolist()))
+                <class 'dict'>
+        """
         return self._array.tolist()
 
     def __array__(self, dtype=None, copy=None):

releasenotes/notes/improve_observables_array_docstring-d6e74b1871e3145c.yaml

@@ -0,0 +1,6 @@
+---
+features_primitives:
+  - |
+    Expanded the docstring of :meth:`.ObservablesArray.tolist`
+    to make it clear it might return a scalar in the case
+    the observables array is of dimension 0.