GodotModding / GodotModding/godot-mod-loader
Doc Comment updates
- 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
Assessment
This issue has not been assessed yet.