From da28edd1df77a5e1668af57e6da2f6e563c7338b Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Fri, 30 Apr 2021 16:42:09 +0200
Subject: [PATCH] Further negotiation for good row types docs

Improvements can be made, however I would rather merge this branch to
master and improve the whole docs.
---
 docs/advanced/rows.rst    | 23 ++++++++++++++++-------
 psycopg3/psycopg3/rows.py | 11 ++++-------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/docs/advanced/rows.rst b/docs/advanced/rows.rst
index f75dc2024..f130b6097 100644
--- a/docs/advanced/rows.rst
+++ b/docs/advanced/rows.rst
@@ -16,13 +16,22 @@ protocol) is a callable that accepts a `Cursor` object and returns another
 callable (formally the `~psycopg3.rows.RowMaker` protocol) accepting a
 `values` tuple and returning a row in the desired form.
 
-.. autoclass:: psycopg3.rows.RowMaker
+.. autoclass:: psycopg3.rows.RowMaker()
 
-   .. automethod:: __call__
+   .. method:: __call__(values: Sequence[Any]) -> Row
 
-.. autoclass:: psycopg3.rows.RowFactory
+        Convert a sequence of values from the database to a finished object.
+
+
+.. autoclass:: psycopg3.rows.RowFactory()
+
+   .. method:: __call__(cursor: AnyCursor[Row]) -> RowMaker[Row]
+
+        Inspect the result on a cursor and return a `RowMaker` to convert rows.
+
+        `!AnyCursor` may be either a `~psycopg3.Cursor` or an
+        `~psycopg3.AsyncCursor`.
 
-   .. automethod:: __call__
 
 `~RowFactory` objects can be implemented as a class, for instance:
 
@@ -75,13 +84,13 @@ The module `psycopg3.rows` provides the implementation for a few row factories:
 
 .. currentmodule:: psycopg3.rows
 
-.. autofunction:: tuple_row
+.. autofunction:: tuple_row(cursor: AnyCursor[TupleRow])
 .. autodata:: TupleRow
 
-.. autofunction:: dict_row
+.. autofunction:: dict_row(cursor: AnyCursor[DictRow])
 .. autodata:: DictRow
 
-.. autofunction:: namedtuple_row
+.. autofunction:: namedtuple_row(cursor: AnyCursor[NamedTuple])
 
 
 Use with a static analyzer
diff --git a/psycopg3/psycopg3/rows.py b/psycopg3/psycopg3/rows.py
index f295e0085..4aafe3500 100644
--- a/psycopg3/psycopg3/rows.py
+++ b/psycopg3/psycopg3/rows.py
@@ -31,13 +31,10 @@ class RowMaker(Protocol[Row_co]):
     program would like to receive: by default (`tuple_row()`) it is a simple
     tuple, but it may be any type of object.
 
-    Typically, `~RowMaker` functions are returned by `RowFactory`.
+    Typically, `!RowMaker` functions are returned by `RowFactory`.
     """
 
     def __call__(self, __values: Sequence[Any]) -> Row_co:
-        """
-        Convert a sequence of values from the database to a finished object.
-        """
         ...
 
 
@@ -56,9 +53,6 @@ class RowFactory(Protocol[Row]):
     """
 
     def __call__(self, __cursor: "AnyCursor[Row]") -> RowMaker[Row]:
-        """
-        Inspect the result on a cursor and return a `RowMaker` to convert rows.
-        """
         ...
 
 
@@ -75,6 +69,7 @@ def tuple_row(
 
     This is the default factory.
 
+    :param cursor: The cursor where the rows are read.
     :rtype: `RowMaker`\ [`TupleRow`]
     """
     # Implementation detail: make sure this is the tuple type itself, not an
@@ -99,6 +94,7 @@ def dict_row(
     Note that this is not compatible with the DBAPI, which expects the records
     to be sequences.
 
+    :param cursor: The cursor where the rows are read.
     :rtype: `RowMaker`\ [`DictRow`]
     """
 
@@ -117,6 +113,7 @@ def namedtuple_row(
 ) -> Callable[[Sequence[Any]], NamedTuple]:
     r"""Row factory to represent rows as `~collections.namedtuple`.
 
+    :param cursor: The cursor where the rows are read.
     :rtype: `RowMaker`\ [`NamedTuple`]
     """
 
-- 
2.47.2