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 parse
    self.do_post_block_processing_cleanup()
  File "C:\Users\alexw\coding\cpython\Tools\clinic\clinic.py", line 5583, in do_post_block_processing_cleanup
    assert 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 ;)