GodotModding / GodotModding/godot-mod-loader

Doc Comment updates

Open
#513 1 comment 0 reactions 0 assignees View on GitHub
4.x documentation
Dominant language
GDScript
Stars
675
Forks
54
Avg merge
2m
Merged PRs (30d)
2

Description

- [x] Unify the parameter descriptions

Planned Format

```
ReturnType method_name(param_name: Type, param_two: Type) modifiers
Short one line method desc

Parameters:
- [param param_name] ([Type]): Full param description - what it is and what format it may require
- [param param_two] ([Type]): ...

Returns:
- [code][Type][/code] Description of what the return value is
or for void: "No return value"

Description:
Long method description

Examples:
code with descriptions
```
As a doc comment (some parts are automatically generated and not part of the comment):
```gdscript
## Adds all methods from a file as hooks.[br]
## [br]
## Parameters:[br]
## - [param vanilla_script_path] ([String]): File path of the vanilla script to be hooked.[br]
## - [param hook_script_path] ([String]): Path to the mod script containing your hook methods.[br]
## [br]
## No return value[br]
## [br]
## Description:[br]
## The file needs to extend [Object].[br]
## The methods in the file need to have the exact same name as the vanilla method
## they intend to hook, all mismatches will be ignored.[br]
## See: [method add_hook][br]
## [br]
## Examples:[br]
## Addind a script hook file in [code]mod_main.gd[/code][br]
## [codeblock]
## ModLoaderMod.install_script_hooks(
## "res://tools/utilities.gd",
## extensions_dir_path.path_join("tools/utilities-hook.gd")
## )
## [/codeblock]
static func install_script_hooks(vanilla_script_path: String, hook_script_path: String) -> void:
pass
```

- [x] unify bbcode note/callout syntax - must be valid bbcode to look okay in engine and must be unique for us to parse into md


Planned Format

- everything between opening === and closing === is a callout
- the first line is always discarded in favor of the default titles
- optional: the type/color can be changed and a custom title can be set
- by using a (technically invalid but invisible) empty bbcode [color] tag
- example:
```gdscript
## ===[br]
## [b]Note:[color=note "A note on paths"][/color][/b][br]
## Your extender script doesn't have to follow the same directory path as the vanilla file,
## but it's good practice to do so.[br]
## ===[br]
```

- [ ] add [`@deprecated`](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html#deprecated-and-experimental-tags) tags where appropriate
- [ ] add bbcode links to mentioned classes, parameters, signals (`Object` -> `[Object]`, `mod_id` -> `[param mod_id]`...)
- [ ] add doc comment guide to CONTRIBUTING.md
- [ ] prefix non public variables with _

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.