Skip to content

Doc Comment updates #513

Open
Open
@Qubus0

Description

@Qubus0
  • 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 _

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    4.xdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions