GDScript: Add @deprecated and @experimental doc comment tags

[dalexeev]

These attributes are already available in the core documentation, so I think making it available in GDScript documentation is an obvious step. The @tag syntax is already used (@tutorial) and is similar to JavaDoc.

## Decription
## @experimental
## @deprecated
var a

Added support for multiline doc comments for enum values:

## Enum description.
## @experimental
## @deprecated
enum MyEnum {
    ## Enum value 0 description.
    ## @experimental
    ## @deprecated
    VALUE_A,
    ## Enum value 1 description.
    ## @experimental
    ## @deprecated
    VALUE_B,
}

Regarding inline (single line) doc comments:

1. they don't always work correctly - for multiline definitions (functions, classes);
2. they don't support tags and, obviously, multiline [codeblock]s.

Test script 1 - multiline doc comments

extends Node
## Class brief.
##
## Class description.
##
## @tutorial: https://url.com
## @experimental
## @deprecated

## Nested class brief.
##
## Nested class description.
##
## @tutorial: https://url.com/nested/
## @experimental
## @deprecated
class Inner:
    ## Nested class var description.
    ## @experimental
    ## @deprecated
    var a

## Var description.
## @experimental
## @deprecated
var a

## Const description.
## @experimental
## @deprecated
const A = 1

## Signal description.
## @experimental
## @deprecated
signal s()

## Func description.
## @experimental
## @deprecated
func f():
    pass

## Enum description.
## @experimental
## @deprecated
enum MyEnum {
    ## Enum value 0 description.
    ## @experimental
    ## @deprecated
    VALUE_A,
    ## Enum value 1 description.
    ## @experimental
    ## @deprecated
    VALUE_B,
}

Test script 2 - inline doc comments

extends Node

class Inner: ## Nested class brief.
    var a ## Nested class var description.

var a ## Var description.

const A = 1 ## Const description.

signal s() ## Signal description.

func f(): ## Func description.
    pass

enum MyEnum { ## Enum description.
    VALUE_A, ## Enum value 0 description.
    VALUE_B, ## Enum value 1 description.
} ## End enum.

[adamscott]

I added the PR to the PRs to review by the team.

[adamscott]

Seems fine to me!

[dalexeev]

I simplified the code a bit. Actually, I'd like to fix the single-line doc comments and some edge cases, but the full syntax already looks fine and further improvements don't related directly to the PR title.

[adamscott]

Reviewed in the weekly GDScript meeting. Approved! Thanks @dalexeev!

[anvilfolk]

For posterity and documentation purposes, this reintroduces an EnumDoc struct, which is slightly different to the one originally removed by #72095. Back then, I found the EnumDoc struct was created during docgen but then not actually used, so I removed it. A single String was enough to implement all the features required at the time.

But with experimental and deprecated flags, that information needs to be stored somewhere, so it makes sense this struct had to be reintroduced :)

[adamscott]

Discussed in the meeting after the approval: what about implementing the @deprecated and @experimental doc tags as function/enum/var annotation?

@deprecated("Use [that function] instead")
func my_func():
    pass

It could make it so that it would be usable by other systems than just the documentation?

[anvilfolk]

Discussed in the meeting after the approval: what about implementing the @deprecated and @experimental doc tags as function/enum/var annotation?

@deprecated("Use [that function] instead")
func my_func():
    pass

It could make it so that it would be usable by other systems than just the documentation?

I like this a lot - so these flags could actually exist within the GDScript typing datastructures themselves, like ClassNode, FunctioNode, etc :)

[dalexeev]

It could make it so that it would be usable by other systems than just the documentation?

In theory, we can use doc comments for other systems as well. Note that this uses the BBCode Editor Help markup.

## @deprecated: Use [method function] instead.

This is implemented this way for the most part only because the data is stored in DocData, and not in ClassDB for example, and it seemed logical to process this with descriptions. Also currently deprecated and experimental are boolean attributes, not strings. We could change it, but this is a core issue.

The only significant difference between annotations and doc comments is that annotations support constant expressions as arguments. In theory, you might want to do something like

const DEPRECATED_TEMPLATE = 'Property "%s" is deprecated. Do not use it.'

@deprecated(DEPRECATED_TEMPLATE % "a")
var a

@deprecated(DEPRECATED_TEMPLATE % "b")
var b

but this seems to be a bit of a far-fetched example.

[YuriSizov]

I agree, so far this is only a documentation concept and it only comes as a boolean flag. If we want to make the system more versatile, it needs to happen in ClassDB as well, not just in GDScript.

[YuriSizov]

Thanks!

[DSPerson]

cool