GDScript Documentation Guide

This file defines the rules and template for writing API documentation across all GDScript codebases in the organisation.
It is intended to be read and followed by both human authors and AI models generating documentation from source code.

Part 1 — Rules

1. General Philosophy

Documentation describes what a thing does and why it matters, not how it is implemented internally.
Write for an audience that is technically competent but unfamiliar with this specific codebase. Do not over-explain GDScript or Godot basics. Do not under-explain domain-specific behaviour.
Every documented item must be accurate to the source. If something is unclear in the code, document what the code actually does — not what it might intend to do.
Do not copy GDScript doc comments verbatim. Rewrite them in prose that reads naturally in a reference document.
Keep descriptions concise but complete. Prefer one clear sentence over three vague ones.

2. 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. Exception: do not document constants that are defined purely as enum aliases from another class (e.g. const MessageType: ConstaNetHeadder.Type = ConstaNetHeadder.Type). These add no information beyond what is already in the source class. Wherever such a constant would be referenced in the documentation, replace it with the fully qualified original type (e.g. use ConstaNetHeadder.Type not MessageType).
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. Exception: if the class is a static class that defines _static_init instead of _init, do not add a _init entry to the Public API. Static classes are not instantiated and have no constructor to document.
Public API — all public methods and properties (those 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

Do not document the following:

Private methods and variables (any identifier prefixed with _), with the sole exception of _init in non-static classes
Internal implementation details (socket polling loops, buffer management, etc.)
GDScript lifecycle methods other than _init (_process, _notification, etc.) unless they form part of the public contract
Transient internal state variables that have no public accessor

3. Formatting & Markdown Style

3.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
## Constants
## Enums                         (if applicable)
## SettingsManager Entries       (if applicable)
## Member Variables              (if applicable)
## Public API
## Command-Line Arguments        (if applicable)
## InnerClassName                (one section per inner class)
## Notes                         (if applicable)

3.2 Headings

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

Never skip heading levels. Never use #### or deeper for primary content — use bold text or tables instead.

3.3 Metadata Line

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


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

If there is no parent beyond Object, omit the extends portion.

3.4 Copyright Block

Immediately below the metadata line:


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

3.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.
 
Additional paragraphs if needed. Use bullet lists only when enumerating distinct behaviours, not for padding.

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

3.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. |

Do not document each constant as a separate ### heading.

3.7 Enums

Each enum gets its own ### heading under ## Enums. Document every named value in a table with its integer value and a description. The integer values must match the source exactly — do not assume GDScript’s default auto-increment if values are not explicit; look them up or ask.


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

3.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 reflects 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. |

SETTING — a value that is not intended to change during normal runtime, but can be modified.
CONTROL — a value intended to be actively modified at runtime.
STATUS — read-only. Reflects internal state; cannot be set externally.

3.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. Use cross-references where the type is documented elsewhere in the same file.


## Member Variables
 
### `variable_name`
 
*DataType:* `Type`  
*Default:* `value`  
Description. Cross-reference to related types or sections where relevant. See [`Type`](#type).
 
---
 
### `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, omit the *Default:* line entirely — do not guess or infer one.

3.10 Enum Alias Constants

Constants that exist solely to alias an enum from another class (e.g. const MessageType: ConstaNetHeadder.Type = ConstaNetHeadder.Type) must not be included in the Constants table. They carry no independent meaning and their presence in the table would be misleading.

When one of these aliased names would appear elsewhere in the documentation (e.g. in a method description), always use the fully qualified original reference instead:

✓ ConstaNetHeadder.Type
✗ MessageType

3.11 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.

3.12 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 (the file link is already present in the outer class header), 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
...

3.13 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. When a default value is not explicitly specified, omit the = default portion entirely — do not guess or infer a value.


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

3.14 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()

3.15 Cross-References

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


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

Use backticks inside the link label for any identifier (method, class, variable name).

3.16 Horizontal Rules

Use --- to separate major sections. Do not use --- between individual method entries within a section — let headings provide the visual separation.

4. Tone & Language

Use present tense throughout. “Returns the local node.” not “Will return the local node.”
Use active voice. “Emits node_found.” not “node_found is emitted.”
Be direct. Start method descriptions with a verb. “Starts the network stack.” not “This method is used to start the network stack.”
Use “the local node”, “the session”, “the network handler” as definite references — not “a node” or “some session” when referring to the specific object the class manages.
Avoid filler phrases: “Note that”, “It is important to”, “Please be aware”, “Simply”, “Just”.
Avoid anthropomorphising the code: “the engine knows”, “the handler thinks”. Prefer “the handler tracks”, “the engine stores”.
Spell out abbreviations on first use within a section if they are not universally standard. (TCP, UDP, UUID, IP are fine without expansion.)
Use Oxford commas.
Use sentence case for description text. Use the exact capitalisation of identifiers when referring to them in backticks.

5. Accuracy Rules

These are non-negotiable for both human authors and AI models:

Never infer undocumented behaviour. If the code does not clearly show that a method does something, do not document it as doing that thing.
Never document private methods, with the sole exception of _init. Any other method or variable prefixed with _ is internal — do not include it in output documentation, even if it is interesting or complex.
Always use Variant for undeclared types. If a parameter, return type, or property has no explicit type annotation in the source, document its type as Variant. Do not guess.
Never fabricate default values. If a default value is not explicitly present in the source signature, omit the = default portion entirely.
Never copy error strings or internal log messages as documentation content.
When in doubt about what a method does, document only what is provably true from the source. A shorter, accurate description is always preferable to a longer, speculative one.

6. AI Model–Specific Instructions

When generating documentation from a source file, follow this process in order:

Read the entire file before writing any output. Do not begin documenting after reading only part of the file.
Identify the class name, parent, and file path for the header.
List all public identifiers (no _ prefix): signals, constants, enums, member variables, methods, inner classes. Also include _init.
Discard all other private identifiers (_ prefix, excluding _init). Do not reference them anywhere in the output, even parenthetically.
Filter enum alias constants. Any constant defined as const X: SomeClass.Enum = SomeClass.Enum is an alias and must be excluded from the Constants table. When that name would appear in descriptions, replace it with the fully qualified original (e.g. ConstaNetHeadder.Type, not MessageType).
Always document _init, even if it takes no arguments. Place it as the first entry under ## Public API. Use *Args:* null if there are no parameters. Exception: if the class defines _static_init instead of _init, it is a static class — do not add a _init entry at all.
For each public method and _init, determine: what it does, what arguments it takes (names, types, defaults), what it returns, and any side effects or error conditions visible from the source.
Use Variant for any parameter, return type, or property with no explicit type annotation in the source. Do not infer or assume a type.
Omit default values for any parameter that does not have one explicitly stated in the source signature.
Document all enums under ## Enums, each as a ### subsection with a value table. Integer values must be taken from the source exactly.
Document all public member variables and static variables under ## Member Variables, each as a ### entry with *DataType:*, *Default:* (if explicitly set in source), and a description. Omit *Default:* if no default is set. Place this section directly before ## Public API.
Document all _settings registrations under ## SettingsManager Entries as a single table. Identify the EntryType from the registration method: register_setting → SETTING, register_control → CONTROL, register_status → STATUS.
Write each section in the order defined in the template below. Do not reorder sections.
Do not pad output. If a section has no content (e.g., no signals), omit the section header entirely.
Validate against the rules in sections 2–5 before finalising output.

When to Ask Questions

If anything in the source code is ambiguous — a method whose purpose cannot be determined from its name, body, and doc comment alone — stop and ask before documenting it. Do not guess. Do not write a vague description to fill the space.

Specifically, ask when:

A method’s behaviour depends on external state or systems not visible in the file
A method name is unclear or could reasonably mean more than one thing
A parameter’s role or expected values are not inferable from its name and type alone
A return value’s meaning is not obvious (e.g. a bool or int with no doc comment)
An inner class or constant has a name that is not self-explanatory

When asking, be specific. Quote the method signature and state exactly what is unclear. Do not ask about things that are clearly readable from the source.

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.
 
---
 
## Constants
 
| Name | Type | Value | Description |
|------|------|-------|-------------|
| `CONSTANT_NAME` | `Type` | `value` | Description. |
 
---
 
## Enums
 
### `EnumName`
 
Description of what this enum represents and where it is used.
 
| Name | Value | Description |
|------|-------|-------------|
| `VALUE_A` | `0` | Description. |
| `VALUE_B` | `1` | 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.