Add support for multiple line comment blocks in GDScript

[tx350z]

Describe the project you are working on:
A MMORPG space game using a realistic ship GUI simulation. The main game display includes a large number of GUI controls with complex inter-dependencies.

Describe the problem or limitation you are having in your project:
"Self-documenting" code is fine for projects that have a small code base. My project involves many GUI elements with complex interdependencies. Single line comments are insufficient to document both the "what" and (more importantly) the "why" of functions and code blocks. Multiple single-line comments can be used but are not collapsible in the editor. When several lines of comments are present, actual code becomes buried.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:
Implement support for comment blocks found in most programming languages and allow the comment blocks to be collapsible like code blocks. /** */ is a commonly used syntax though many others exist.
Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:

/**
comment line 1
comment line 2
comment line 3
*/

If this enhancement will not be used often, can it be worked around with a few lines of script?:
I personally will use this often and believe others will also.

Is there a reason why this should be core and not an add-on in the asset library?:
Not sure if it can be done as an add-on.

[Calinou]

GDScript doesn't use a C-style syntax, so /* */ comments would look out of place.

You can use multiline strings ("""like this""") as comments, but keep in mind GDScript has no actual multiline comments. Multiline strings happen to be standalone expressions and will still be evaluted by the GDScript parser.

Multiple single-line comments can be used but are not collapsible in the editor.

It would be possible to make them collapsible without adding a multiline comment syntax: #416

[tx350z]

I am aware of the multiline strings. In my opinion using them as a substitue to a multiline comment potentially exposes proprietary info to end users since strings are included in the compiled "binary" while comments aren't (or shouldn't be anyway).

[aaronfranke]

Some languages with multi-line comments have migrated away from them. For example, in C#, the most common way to write multi-line comments is by having many lines which all start with //, and inline documentation starts with ///.

[lmcdd]

Use
"""
Text
Text
Text
"""

[h0lley]

@tx350z you are probably already aware, but ctrl + k (toggle comment state for selected text/block) may be a satisfying substitute.

[tx350z]

Yes, I am aware.

[Xrayez]

Commenting with Ctrl + K has its issues (not sure if feature or bug):

So, it doesn't seem to work for those comments which are inside blocks, so I'd focus on making single-line comment/uncomment to work regardless of whether multiple line comment blocks are added in GDScript. I'd personally make the comment/uncomment behavior consistent with VS Code (which is what makes it break in Godot editor for me, in fact).

[liryu1973]

@Xrayez That's probably normal behavior.
Ctrl+k is for writing and erasing #'s on the left side of the line.
It does not interfere with the # in the block.
Otherwise, if you were to remove the # in the block, only the comment would be left behind, causing an error.

[Gurigraphics]

I agree to add multiline comments. Multiline strings the user/dev experience is very bad.
My proposal is to substitute for "/// ///" which does not require pressing shift, as I wrote in the topic indicated above in more detail.

[aaronfranke]

If we do decide to have multi-line comments, /* */ is more sane syntax than /// which no languages use (AFAIK).

I don't think we need multi-line comments though.

[Gurigraphics]

which no languages use (AFAIK).

hehe
That's exactly why we need to use it. To be the pioneers.

[tx350z]

I understand that code commenting is out of favor. However, some things benefit from detailed commenting. The following is an example of why I'd like to see collapsible multi-line comments in GDScript. This is just one block of comments in a very large script file.

# IpfsParms: Base class for IPFS HTTP API query arguments. Extended for each HTTP API command.
# The property values of this class are translated to query arguments string using HTTPClient.query_string_from_dict().
# Since many of the IPFS commands have optional arguments, the goal is to include ONLY optional
# arguments that are explicitly set. This is accomplished by storing a property name, argument name,
# and argument value in the __parms array.
# The structure of __parms entries is {"<property-name>":{"<argument-name>":<argument-value>};
# The following rules MUST be followed for all of this to work correctly.
# Rules:
#	Every IPFS command MUST have an associated parameters class even if the command supports no arguments.
#	If the IPFS command has no arguments, the descendent class MUST add {"NOPARMS":{"NOPARMS":true}} to __parms.
#		This is best done in _init(). See BitswapReprovideParms class below for an exmaple.
#	Required arguments MUST be defined as required parameters to _init(). (e.g. _init(_path:String)).
#		See BitswapLedgerParms class below for an example.
#	All parameters passed into _init() MUST be added to the __parms dictionary.
#		The best way to accomplish this is to call the property's setter method.
#		See BitswapLedgerParms class below for an example.
#	Some IPFS commands use the same parameter name (e.g. "arg") multiple times for different purposes in the query string. UGH!
#		Therefore, the order of parameters appended to __parms is CRITICAL. See ConfgParms class below for an example.
#	Optional arguments MUST have a setter method that adds the associated property to __parms array.
#		The recommended naming for setter methods is prefixing the property variable name with '__'.
#		This avoids potential method name collisions with GDScript class methods.
#	Some parameters need name translation (e.g. property "cid_version" becomes parameter "cid-version"),
#		Name translation should be done in the property setter method when adding the value to __parms.
#		Example: {"cid_version":{"cid-version":1}
#		See BitswapLedgerParms class below for an example.

[YuriSizov]

We don't need a special multi-line syntax to make that block collapsible in the editor though.

[Gurigraphics]

If we do decide to have multi-line comments, /* */ is more sane syntax than /// which no languages use (AFAIK).

I did the test and it is possible to use yes. If you really want to use

As I already said: "The # is just a not-so-well-chosen convention that can be overridden".

[dalexeev]

We don't need a special multi-line syntax to make that block collapsible in the editor though.

It's already been done in 4.0-dev.

Documentation comments were added in 4.0-dev.

I really dislike multiline comments (/* */) because they can't contain nested multiline comments.

[tx350z]

If that feature is coming in 4.0 then I'm good with it.

[bluenote10]

I really dislike multiline comments (/* */) because they can't contain nested multiline comments.

That is a very common misconception. Just because they cannot be nested in C/C++ it doesn't mean they cannot be nested in general. It just depends on the language specification. For instance in Rust this is fully supported:

Of course support for nested block comments requires a more complex grammar.

Since GDScript is a hash commented language, it would be more natural though to use #[ ... ]# which is for instance what Nim is using as well, also supporting nesting.

[dalexeev]

@bluenote10

Case 1.

/*
string = "*/"
*/

For example:

/*
...
regex = "/[a-z]*/"
//             ^^
...
*/

Case 2.

/*
// */
*/

Multiline comments are evil.

[Calinou]

We discussed this proposal in a meeting. We found that this proposal lacked support among the community and contributors, so we won't be implementing this.

Improvements to the Ctrl + K commenting system (to improve usability) are welcome though.

[JohnLambe]

I think the /** */ syntax would be misleading since it is the same as JavaDoc (documentation comments). Why not /* */?
[Edit: This was formatted wrongly. Fixed using the code formatting syntax.]

[yerbestpal]

Doesn't godotengine/godot#79761 now make the case for this, since presumably single-line comments below a comment with a comment marker would be contextually independent and thus would surface incorrectly if there were any kind of future interface for browsing markers?

[Calinou]

since presumably single-line comments below a comment with a comment marker would be contextually independent and thus would surface incorrectly if there were any kind of future interface for browsing markers?

The highlighting implemented in the script editor only affects the keyword, not the text associated to it. No effort is currently being made to highlight the associated text.

That said, if this was to be implemented, it's possible to distinguish the associated text from further lines using a line break in the comment:

# TODO: Something
# to be done in the future.
# This is still part of the TODO block.
# 
# This isn't part of the TODO block (and neither is the line break above).

If space alignment is used, it's even possible to distinguish the rest of the comment without a line break:

# TODO: Something
#       to be done in the future.
#       This is still part of the TODO block.
# This isn't part of the TODO block.

[yerbestpal]

That said, if this was to be implemented, it's possible to distinguish the associated text from further lines using a line break in the comment:

# TODO: Something
# to be done in the future.
# This is still part of the TODO block.
# 
# This isn't part of the TODO block (and neither is the line break above).

Great point. Apologies for rousing a closed issue, but it seemed worthwhile.