gh-104683: Argument Clinic: Refactor and simplify 'add docstring' states

[erlend-aasland]

Introduce docstring_append() helper, and use it for both parameter and
function docstrings. Remove docstring fixup from
do_post_block_processing_cleanup(); instead, make sure no fixup is needed.

• Issue: Modernise code in Tools/clinic/ #104683

[AlexWaygood]

Remove docstring fixup from
do_post_block_processing_cleanup(); instead, make sure no fixup is needed.

I think the fixup is still needed. If I apply this diff to your PR branch:

--- a/Tools/clinic/clinic.py+++ b/Tools/clinic/clinic.py@@ -5577,6 +5577,11 @@ def do_post_block_processing_cleanup(self) -> None:
if no_parameter_after_star:
fail("Function " + self.function.name + " specifies '*' without any parameters afterwards.")
+ for name, value in self.function.parameters.items():+ if not value:+ continue+ assert value.docstring == value.docstring.rstrip()+
self.function.docstring = self.format_docstring()

Then the assertion fails in ClinicParserTest.test_function_docstring:

======================================================================
FAIL: test_function_docstring (test.test_clinic.ClinicParserTest.test_function_docstring)
----------------------------------------------------------------------
Traceback (most recent call last):
File "C:\Users\alexw\coding\cpython\Lib\test\test_clinic.py", line 632, in test_function_docstring
function =self.parse_function("""^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\alexw\coding\cpython\Lib\test\test_clinic.py", line 1384, in parse_function
block =self.parse(text)
^^^^^^^^^^^^^^^^
File "C:\Users\alexw\coding\cpython\Lib\test\test_clinic.py", line 1380, in parse
parser.parse(block)
File "C:\Users\alexw\coding\cpython\Tools\clinic\clinic.py", line 4612, in parseself.do_post_block_processing_cleanup()
File "C:\Users\alexw\coding\cpython\Tools\clinic\clinic.py", line 5583, in do_post_block_processing_cleanupassert value.docstring == value.docstring.rstrip()
AssertionError
----------------------------------------------------------------------

[bedevere-bot]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[erlend-aasland]

I think the fixup is still needed. [...]

The docstrings are further processed in format_docstring; I'm not sure it matters that they are off at this point in the parsing.

[AlexWaygood]

I think the fixup is still needed. [...]

The docstrings are further processed in format_docstring; I'm not sure it matters that they are off at this point in the parsing.

Ugh, yes, I think you're right :)

[AlexWaygood]

Thank you! Looks good now the test's been added :)

[erlend-aasland]

Ugh, yes, I think you're right :)

See also the added test ;)