GDScript Documentation Guide

This file defines the rules and template for writing API documentation across all GDScript codebases in the organisation.

Part 1: Rules

1. What to Document

Document the following:

Class header: class name, parent class, source file link, license, and a short description of the class’s responsibility
Signals: all signals, their arguments, and when they are emitted
Constants: all public constants, in a table
Enums: all public enums defined in the class, each in their own ### subsection with a value table
SettingsManager entries: all settings registered via _settings.register_setting(), _settings.register_control(), or _settings.register_status(), in a single table
_init: always document _init, even if it takes no arguments. Use *Args:* null if there are none.
Public API: all public methods and properties (ones without a _ prefix)
Inner classes: documented as their own section within the same file, following the same rules
Command-line arguments: if the class parses OS.get_cmdline_args(), document each flag
Practical notes: a short section at the end for gotchas, platform quirks, or non-obvious behaviour

2. Formatting & Markdown Style

2.1 File Structure

Every documentation file must follow this top-level order:


# ClassName
metadata line (source link, extends)
copyright block
Short class description paragraph

---

## Signals
## Enums
## Constants
## SettingsManager Entries
## Member Variables
## Public API
## Command-Line Arguments
## InnerClassName
## Notes

2.2 Headings

Level	Used for
`#`	Class name
`##`	Top-level sections (Signals, Constants, Public API, inner class names)
`###`	Individual methods, properties, signals, or inner class subsections

2.3 Metadata Line

Immediately below the # heading, add an italic metadata line:


*source:* [`FileName.gd`](url) *extends:* [`ParentClass.gd`](url)

If the parent class is an internal godot class. Link to the relevant godot doc page instead.

2.4 Copyright Block

Immediately below the metadata line:


**Copyright (c) YYYY  
Author Name — All rights reserved.  
Licensed under GPLv3**

The author(s) name and licence name must match what is in the file.

2.5 Method / Property Entries

Each public method or property entry follows this exact structure:


### method_name
 
*Args:*
- `Type: param_name`
- `Type: param_name = default`
 
*Returns:* `Type`
 
Description paragraph. One or more sentences explaining what this method does, what it returns, and any important side effects or error conditions.

If a method takes no arguments, write *Args:* null.
If a method returns nothing, write *Returns:* void.
If a method returns void, still include the line for consistency.

2.6 Constants Table

All constants in a class must be documented together in a single Markdown table:


| Name | Type | Value | Description |
|------|------|-------|-------------|
| `CONSTANT_NAME` | `Type` | `value` | What this constant represents. |

2.7 Enums

Each enum gets its own ### heading under ## Enums. Document every named value in a table with its integer value and a description.


### `EnumName`
 
Description of what this enum represents and where it is used.
 
| Name | Value | Description |
|------|-------|-------------|
| `VALUE_A` | `0` | Description. |
| `VALUE_B` | `1` | Description. |

2.8 SettingsManager Entries

If a class registers settings via its _settings (SettingsManager) member, document all of them together in a single table under ## SettingsManager Entries. The table has four columns: Name, DataType, EntryType, and Description.

EntryType defines which registration method was used:

Registration method	EntryType label
`_settings.register_setting()`	`SETTING`
`_settings.register_control()`	`CONTROL`
`_settings.register_status()`	`STATUS`


## SettingsManager Entries
 
| Name | DataType | EntryType | Description |
|------|----------|-----------|-------------|
| `EntryName` | `Data.Type.TYPE` | SETTING | Description. |
| `EntryName` | `Data.Type.TYPE` | CONTROL | Description. |
| `EntryName` | `Data.Type.TYPE` | STATUS | Description. |

2.9 Member Variables

Public member variables (those without a _ prefix) and public static variables are documented under ## Member Variables. Each variable gets its own ### heading. Document the data type, default value if one is explicitly set in the source, and a description.


## Member Variables
 
### `variable_name`
 
*DataType:* `Type`  
*Default:* `value`  
Description. Cross-reference to related types or sections where relevant. See [`Type`](#type).
 
---
 
### static `another_variable`
 
*DataType:* `Type`  
Description. Omit `*Default:*` if no default is explicitly set in the source.

If a variable has no explicitly set default value in the source, remove the *Default:* line entirely.

2.10 Signals

Each signal gets its own ### heading:


### signal_name
 
*Args:* `Type: arg_name`  
Description of when this signal is emitted and what the argument contains.

If a signal has no arguments, write *Args:* null.

2.11 Inner Classes

Inner classes are documented as a ## section within the same file. They follow the same structure as the top-level class, with two differences: the metadata line uses *Defined in:* with no link, and member variables use #### headings grouped under a ### Member Variables heading.


---
 
## `InnerClassName`
*Defined in:* `FileName.gd`
 
Short description of the inner class's role.
 
---
 
### Member Variables
 
#### `variable_name`
 
*DataType:* `Type`  
*Default:* `value`  
Description.
 
---
 
### Public API
 
### method_name
...

2.12 Untyped Parameters and Missing Defaults

GDScript allows untyped parameters and properties. When a parameter or return type is not explicitly declared in the source, use Variant as the type.


*Args:*
- `Variant: p_value`        # no type declared in source
- `String: p_name = ""`    # type and default both declared

2.13 Code Examples

Use fenced code blocks with the appropriate language tag:

gdscript for GDScript
bash for command-line usage
text for plain examples with no syntax


# Example
constellation.start_node()

2.14 Cross-References

When referencing another documented method, or class, or section within the same repo, use a link anchored to the heading, or file path:


[`method_name`](#method_name)
[`OtherClass`](./OtherClass)

Use backticks inside the link label for any identifier.

Part 2: Template

Copy this template when starting a new documentation file. Replace all PLACEHOLDER values. Remove any section that does not apply.


# `ClassName`
*source:* [`FileName.gd`](GITHUB_URL) *extends:* [`ParentClass.gd`](GITHUB_URL)
 
**Copyright (c) YYYY  
Author Name — All rights reserved.  
Licensed under GPLv3**
 
One to three sentences describing what this class is responsible for. State its role in the system, what it manages, and any high-level constraints or assumptions.
 
---
 
## Signals
 
### `signal_name`
 
*Args:* `Type: arg_name`  
When this signal is emitted and what the argument contains.
 
### `signal_no_args`
 
*Args:* null  
When this signal is emitted.
 
---
 
## Enums
 
### `EnumName`
 
Description of what this enum represents and where it is used.
 
| Name | Value | Description |
|------|-------|-------------|
| `VALUE_A` | `0` | Description. |
| `VALUE_B` | `1` | Description. |
 
---
 
## Constants
 
| Name | Type | Value | Description |
|------|------|-------|-------------|
| `CONSTANT_NAME` | `Type` | `value` | Description. |
 
---
 
## SettingsManager Entries
 
| Name | DataType | EntryType | Description |
|------|----------|-----------|-------------|
| `EntryName` | `Data.Type.TYPE` | SETTING | Description. |
| `EntryName` | `Data.Type.TYPE` | CONTROL | Description. |
| `EntryName` | `Data.Type.TYPE` | STATUS | Description. |
 
---
 
## Member Variables
 
### `variable_name`
 
*DataType:* `Type`  
*Default:* `value`  
Description.
 
---
 
### `variable_no_default`
 
*DataType:* `Type`  
Description.
 
---
 
## Public API
 
### `_init`
 
*Args:*
- `Type: param_name`
- `Type: param_name = default`
 
*Returns:* void
 
Description of what initialisation this constructor performs.
 
### `method_name`
 
*Args:*
- `Type: param_name`
- `Variant: p_untyped_param`
 
*Returns:* `Type`
 
Description.
 
---
 
## Command-Line Arguments
 
### `--flag-name <value>`
 
Description of what this flag overrides and how it affects runtime behaviour.
 
**Example:**
\```bash
--flag-name value
\```
 
---
 
## `InnerClassName`
*Defined in:* `FileName.gd`
 
Description of the inner class's purpose and relationship to the outer class.
 
---
 
### Member Variables
 
#### `variable_name`
 
*DataType:* `Type`  
*Default:* `value`  
Description.
 
---
 
### Public API
 
### `_init`
 
*Args:* null  
*Returns:* void  
 
Description of what this inner class constructor initialises.
 
### `method_name`
 
*Args:* null  
*Returns:* `Type`  
 
Description.
 
---
 
## Notes
 
- Any non-obvious platform behaviour, ordering constraints, or gotchas that do not belong in individual method entries.