From b36eda9bf810cf66776e360e433c0d3943bbc15d Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Tue, 8 Aug 2023 22:49:10 +0200
Subject: [PATCH 1/3] gh-104683: Argument Clinic: Params now render their own
 docstrings

---
 Lib/test/test_clinic.py | 12 ++++++++++--
 Tools/clinic/clinic.py  | 29 +++++++++++++----------------
 2 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py
index 8ed7e214742d50..4ce188dd2b1b57 100644
--- a/Lib/test/test_clinic.py
+++ b/Lib/test/test_clinic.py
@@ -834,8 +834,8 @@ def expect_failure(self, block, err, *, filename=None, lineno=None):
 
     def checkDocstring(self, fn, expected):
         self.assertTrue(hasattr(fn, "docstring"))
-        self.assertEqual(fn.docstring.strip(),
-                         dedent(expected).strip())
+        self.assertEqual(dedent(expected).strip(),
+                         fn.docstring.strip())
 
     def test_trivial(self):
         parser = DSLParser(_make_clinic())
@@ -999,8 +999,12 @@ def test_function_docstring(self):
 
                path: str
                    Path to be examined
+                   Ensure that multiple lines are indented correctly.
 
             Perform a stat system call on the given path.
+
+            Ensure that multiple lines are indented correctly.
+            Ensure that multiple lines are indented correctly.
         """)
         self.checkDocstring(function, """
             stat($module, /, path)
@@ -1010,6 +1014,10 @@ def test_function_docstring(self):
 
               path
                 Path to be examined
+                Ensure that multiple lines are indented correctly.
+
+            Ensure that multiple lines are indented correctly.
+            Ensure that multiple lines are indented correctly.
         """)
 
     def test_docstring_trailing_whitespace(self):
diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index 16f31717080e1f..e696898c84bb3e 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -2775,6 +2775,15 @@ def get_displayname(self, i: int) -> str:
         else:
             return f'"argument {i}"'
 
+    def render_docstring(self) -> str:
+        if not self.docstring:
+            return ""
+        add, out = text_accumulator()
+        add(f"  {self.name}\n")
+        for line in self.docstring.split("\n"):
+            add(f"    {line}\n")
+        return out().rstrip()
+
 
 CConverterClassT = TypeVar("CConverterClassT", bound=type["CConverter"])
 
@@ -5681,22 +5690,10 @@ def add_parameter(text: str) -> None:
     @staticmethod
     def format_docstring_parameters(params: list[Parameter]) -> str:
         """Create substitution text for {parameters}"""
-        text, add, output = _text_accumulator()
-        spacer_line = False
-        for param in params:
-            docstring = param.docstring.strip()
-            if not docstring:
-                continue
-            if spacer_line:
-                add('\n')
-            else:
-                spacer_line = True
-            add("  ")
-            add(param.name)
-            add('\n')
-            stripped = rstrip_lines(docstring)
-            add(textwrap.indent(stripped, "    "))
-        if text:
+        add, output = text_accumulator()
+        docstrings = [p.render_docstring() for p in params if p.docstring]
+        for docstring in docstrings:
+            add(docstring)
             add('\n')
         return output()
 

From 043af9a57fc838635f7e61020a1408c6fd3580fc Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend.aasland@protonmail.com>
Date: Wed, 9 Aug 2023 13:00:24 +0200
Subject: [PATCH 2/3] Address review: use only one loop

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
---
 Tools/clinic/clinic.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index e696898c84bb3e..5d9825fec1e4cd 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -5691,10 +5691,10 @@ def add_parameter(text: str) -> None:
     def format_docstring_parameters(params: list[Parameter]) -> str:
         """Create substitution text for {parameters}"""
         add, output = text_accumulator()
-        docstrings = [p.render_docstring() for p in params if p.docstring]
-        for docstring in docstrings:
-            add(docstring)
-            add('\n')
+        for p in params:
+            if p.docstring:
+                add(p.render_docstring())
+                add('\n')
         return output()
 
     def format_docstring(self) -> str:

From fbe0b2cd72daddb602aee2e92d23aeddc102135a Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Wed, 9 Aug 2023 14:14:36 +0200
Subject: [PATCH 3/3] Remove obsolete docstring check

---
 Tools/clinic/clinic.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index 5d9825fec1e4cd..44b31ffa8b3b41 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -2776,8 +2776,6 @@ def get_displayname(self, i: int) -> str:
             return f'"argument {i}"'
 
     def render_docstring(self) -> str:
-        if not self.docstring:
-            return ""
         add, out = text_accumulator()
         add(f"  {self.name}\n")
         for line in self.docstring.split("\n"):