Allow docstring in function definition

[ZibingZhang]

Overview

Allows a docstring to be defined at the top of the function.

Details

Docstrings (multiline strings) are represented as an ast.Expr(ast.Constant).
When validating that all child statements (minus the last one) in a function definition are of the class ast.Assign, we make an exception if the first one is an ast.Expr(ast.Constant).

References

#104

[odashi]

It looks basically good!

[ZibingZhang]

Thoughts on removing these empty fields from the tests? Would make it easier to read imo / remove some bloat

[odashi]

How about using ast.parse as in some other tests?

tree = ast.parse(textwrap.dedent("""\
    def f(x):
        '''docstring'''
        return x
    """)).body[0]
assert isinstance(tree, ast.FunctionDef)

[ZibingZhang]

def test() -> None:
    tree = ast.parse(
        """
def f(x):
    '''docstring'''
    return x"""
    )

I've gone with this format. Unfortunately due to the nature of multiline strings it seems like the def can't have any preceding indentation, which makes it a bit awkward to read, but still better than before.

There can't be any space between the last non-whitespace character and the closing """.

I decided to opt against the starting \ because it doesn't actually add anything in terms of the test, and I felt that it's better to keep it simple for readability.

edit: could probably add this function into test_utils if it's commonly used, but since it's only two cases that can probably get held off

[odashi]

could probably add this function into test_utils if it's commonly used

I think this is not recommended according to the DAMP principle. It is somewhat desirable to write self-contained tests:
https://abseil.io/resources/swe-book/html/ch12.html#tests_and_code_sharing_dampcomma_not_dr

[odashi]

Great, thanks!