Skip to content

--reorder-code inserts a blank line between a ## doc comment and its declaration at the class-doc / first-member boundary #260

Description

@minami110

Tested on gdscript-formatter 0.21.0 (Pre-release 0.21.0-beta, published 2026-07-12), Linux x86_64. Upstream main checked up to 248fa13b (2026-07-12 09:20 UTC "Fix comments losing newlines between them in some cases") — that commit is related but in the opposite direction (comments losing newlines vs the bug here, comments gaining an unwanted newline). No fix found for this specific case.

Impact (style-guide deviation, non-breaking)

The GDScript style guide — Documentation Comments requires ## doc comments to sit directly above the declaration they document, with no blank line between. --reorder-code moves an existing blank line from between two ## blocks to between the second ## block and its declaration — losing the class-doc / member-doc boundary and turning the member doc into a free-floating comment.

Trigger

A file where the class-level ## doc block is separated from the first member's own ## doc comment by a blank line (i.e. the file is already correctly structured per the style guide).

Repro

Input (bug.gd):

class_name Foo
extends RefCounted
## file-level class doc block line 1
## file-level class doc block line 2

## member doc for MY_CONST directly above
const MY_CONST := 1

Command:

gdscript-formatter --stdout --reorder-code bug.gd

Actual output (--reorder-code)

class_name Foo
extends RefCounted
## file-level class doc block line 1
## file-level class doc block line 2
## member doc for MY_CONST directly above

const MY_CONST := 1

The blank line originally separating the class doc from the member doc has been moved to after the member doc, breaking the doc/declaration association.

Actual output (without --reorder-code)

class_name Foo
extends RefCounted
## file-level class doc block line 1
## file-level class doc block line 2

## member doc for MY_CONST directly above
const MY_CONST := 1

Plain formatting preserves the blank line's original position. The bug is specific to --reorder-code.

Expected

--reorder-code should leave the blank line where it was (between the class-doc block and the member-doc block), not relocate it to between the member-doc block and its declaration.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Fields

    No fields configured for Bug.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions