docs: clarify figure factory return types (#5396)

Author: senanurcetin

plotly/figure_factory/_quiver.py

@@ -27,7 +27,10 @@ def create_quiver(
         for more information on valid kwargs call
         help(plotly.graph_objs.Scatter)
 
-    :rtype (dict): returns a representation of quiver figure.
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        A Plotly figure containing the quiver arrows.
 
     Example 1: Trivial Quiver
 

plotly/figure_factory/_streamline.py

@@ -55,7 +55,10 @@ def create_streamline(
         for more information on valid kwargs call
         help(plotly.graph_objs.Scatter)
 
-    :rtype (dict): returns a representation of streamline figure.
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        A Plotly figure containing the streamlines and arrows.
 
     Example 1: Plot simple streamline and increase arrow size
 

tests/test_optional/test_figure_factory/test_return_type_docs.py

@@ -0,0 +1,28 @@
+"""Figure-factory return type documentation regression checks."""
+
+import inspect
+
+import pytest
+
+import plotly.figure_factory as ff
+from plotly.graph_objects import Figure
+
+
+@pytest.mark.parametrize(
+    "factory, kwargs",
+    [
+        (ff.create_quiver, {"x": [0], "y": [0], "u": [1], "v": [1]}),
+        (
+            ff.create_streamline,
+            {
+                "x": [0, 1, 2],
+                "y": [0, 1, 2],
+                "u": [[1, 1, 1], [1, 1, 1], [1, 1, 1]],
+                "v": [[1, 1, 1], [1, 1, 1], [1, 1, 1]],
+            },
+        ),
+    ],
+)
+def test_factory_return_docs_match_runtime(factory, kwargs):
+    assert "Returns\n-------\nplotly.graph_objects.Figure" in inspect.getdoc(factory)
+    assert isinstance(factory(**kwargs), Figure)