Skip to content

Doc Comment updates #513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
2 of 6 tasks
Qubus0 opened this issue Jan 12, 2025 · 1 comment
Open
2 of 6 tasks

Doc Comment updates #513

Qubus0 opened this issue Jan 12, 2025 · 1 comment
Labels
4.x documentation Improvements or additions to documentation

Comments

@Qubus0
Copy link
Collaborator

Qubus0 commented Jan 12, 2025

  • 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):

    ## 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
  • 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:
     ## ===[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 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 _

@Qubus0 Qubus0 added documentation Improvements or additions to documentation 4.x labels Jan 12, 2025
@KANAjetzt KANAjetzt added this to the 4.x - 7.0.0 milestone Jan 12, 2025
@Qubus0 Qubus0 removed this from the 4.x - 7.0.0 milestone Feb 16, 2025
@Qubus0
Copy link
Collaborator Author

Qubus0 commented Feb 16, 2025

rest of the todos are not super important for the milestone but should still be remembered

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
4.x documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants