mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

gh-104683: Argument Clinic: Params now render their own docstrings (#107790)

Browse source 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Erlend E. Aasland 2023-08-09 14:44:26 +02:00 • committed by GitHub
parent 65ce3652fa
commit 1b3f5f24af
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

12
Lib/test/test_clinic.py
View file

@ -833,8 +833,8 @@ class ClinicParserTest(TestCase):
def checkDocstring(self, fn, expected): def checkDocstring(self, fn, expected):
self.assertTrue(hasattr(fn, "docstring")) self.assertTrue(hasattr(fn, "docstring"))
self.assertEqual(fn.docstring.strip(), self.assertEqual(dedent(expected).strip(),
dedent(expected).strip()) fn.docstring.strip())
def test_trivial(self): def test_trivial(self):
parser = DSLParser(_make_clinic()) parser = DSLParser(_make_clinic())
@ -997,8 +997,12 @@ class ClinicParserTest(TestCase):
path: str path: str
Path to be examined Path to be examined
Ensure that multiple lines are indented correctly.
Perform a stat system call on the given path. 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, """ self.checkDocstring(function, """
stat($module, /, path) stat($module, /, path)
@ -1008,6 +1012,10 @@ class ClinicParserTest(TestCase):
path path
Path to be examined 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): def test_docstring_trailing_whitespace(self):

27
Tools/clinic/clinic.py
View file

@ -2775,6 +2775,13 @@ class Parameter:
else: else:
return f'"argument {i}"' return f'"argument {i}"'
def render_docstring(self) -> str:
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"]) CConverterClassT = TypeVar("CConverterClassT", bound=type["CConverter"])
@ -5686,23 +5693,11 @@ class DSLParser:
@staticmethod @staticmethod
def format_docstring_parameters(params: list[Parameter]) -> str: def format_docstring_parameters(params: list[Parameter]) -> str:
"""Create substitution text for {parameters}""" """Create substitution text for {parameters}"""
text, add, output = _text_accumulator() add, output = text_accumulator()
spacer_line = False for p in params:
for param in params: if p.docstring:
docstring = param.docstring.strip() add(p.render_docstring())
if not docstring:
continue
if spacer_line:
add('\n') add('\n')
else:
spacer_line = True
add(" ")
add(param.name)
add('\n')
stripped = rstrip_lines(docstring)
add(textwrap.indent(stripped, " "))
if text:
add('\n')
return output() return output()
def format_docstring(self) -> str: def format_docstring(self) -> str: