Make documentation comment parsing more flexible

[vvye]

Describe the project you are working on

This would apply to any project that uses GDScript.

Describe the problem or limitation you are having in your project

I like to document my code, and it's nice to be able to integrate function&variable descriptions in the editor with Godot's documentation comments. However, in order to be shown in the editor, it looks like documentation comments must be immediately preceding the function/variable definition:

## Calculates the factorial of n.
## n must be non-negative.
func factorial(var n: int) -> int:
    if n == 0:
        return 1
    return n * factorial(n - 1)

Godot currently does not support having new lines after the doc comment, or having a comment between the doc comment and the function definition:

## Calculates the factorial of n.
## n must be non-negative.

# An iterative solution would probably be better in terms of memory usage, but this should work for now.
# See https://www.example.com for more info.

func factorial(var n: int) -> int:
    if n == 0:
        return 1
    return n * factorial(n - 1)

I often like to write comments this way, so support for it would be a nice addition.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Make the parsing of documentation comments more flexible, so the documentation comment is recognized as belonging to the function/variable even with whitespace/non-documentation comments between them.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

This would probably involve https://github.com/godotengine/godot/blob/b15b24b087e792335d919fd83055f50f276fbe22/modules/gdscript/gdscript_parser.cpp#L758 .

Currently, the code only checks if the next line also begins with "##". It should also allow empty lines and lines starting with a single "#", or anything that's not code (but not include those lines in the documentation).

If this enhancement will not be used often, can it be worked around with a few lines of script?

This seems very clearly baked into the editor - I'm not sure if it can be worked around with a plugin.

Is there a reason why this should be core and not an add-on in the asset library?

Even if this can be solved with an add-on, it seems strange to not build it into Godot by default.