From 1cd3b20a0eb7281427eb22f33d7323ba173a50bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Senanur=20=C3=87etin?= <senanur.cetin.work@gmail.com>
Date: Fri, 16 Oct 2026 21:21:14 +0300
Subject: [PATCH] docs: clarify figure factory return types (#5396)

---
 plotly/figure_factory/_quiver.py              |  5 +++-
 plotly/figure_factory/_streamline.py          |  5 +++-
 .../test_return_type_docs.py                  | 28 +++++++++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_optional/test_figure_factory/test_return_type_docs.py

diff --git a/plotly/figure_factory/_quiver.py b/plotly/figure_factory/_quiver.py
index fa182222881..f3803345604 100644
--- a/plotly/figure_factory/_quiver.py
+++ b/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
 
diff --git a/plotly/figure_factory/_streamline.py b/plotly/figure_factory/_streamline.py
index 55b74c3e7b7..a8fb59947de 100644
--- a/plotly/figure_factory/_streamline.py
+++ b/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
 
diff --git a/tests/test_optional/test_figure_factory/test_return_type_docs.py b/tests/test_optional/test_figure_factory/test_return_type_docs.py
new file mode 100644
index 00000000000..7ffc17d0d28
--- /dev/null
+++ b/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)