From a9aa9c93342eedcdbcf80e92c08b9efd58f61d22 Mon Sep 17 00:00:00 2001 From: Bloo Date: Sat, 28 Feb 2026 14:24:06 +0100 Subject: [PATCH 1/2] Update Header Comment Documentation --- docs/code-conventions.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/code-conventions.md b/docs/code-conventions.md index bb9bb2e2d1..8cb2b8952b 100644 --- a/docs/code-conventions.md +++ b/docs/code-conventions.md @@ -22,23 +22,28 @@ ## Comments ### Function headers -All functions should start with a header comment that consists of: +All functions should start with a header comment to make review and debugging easier. Such a header comment could look like: ```mcfunction -# Plays a particle animation upon Zauber Cauldron creation -# @s = player holding enchanted book -# at @s align xyz -# run from zauber_cauldrons:cauldron/create +# Demonstrates how header comments work. +# @s = Player in survival, while tabbed-out +# at @s align xyz rotated as @r +# run from gm4:load +# scheduled from gm4:main +# with $id = Id of the player who's tabbed out +# with $timestamp = Timestamp at which the player tabbed out in seconds ``` -1. (Optional) A human-readable description of the function, e.g. `# Plays a particle animation upon Zauber Cauldron creation`. -2. Executor information may be written in mcfunction format (e.g. `# @s = @e[type=mooshroom,limit=1,dx=0]`) or in human-readable format (e.g. `# @s = Mooshroom within same blockspace, limit=1`). Complicated selectors should be written in a human-readable format. -3. Location information should include the full location (including any `align` or `positioned` arguments) or be written in human-readable format if the location is especially complicated. -4. Call information can reference: - - a single function, if the function is run by `/function ...`: `# run from zauber_cauldrons:cauldron/create`. - - a folder, if multiple functions call this function using `/function`: `# run from functions in gm4_pig_tractors:till/blocks/`. - - a function from where it was scheduled: `# scheduled by zauber_cauldrons:cauldron/create`. - - a function and function-tag pair: `# run from gm4_custom_crafters-3.0:process_input/check_item via #gm4_custom_crafter:custom_item_checks`. - - an advancement reward: `# run from advancement damaged/armor/stall` - - a combination of these, in which multiple lines may be used. +Some of the shown lines are optional, in which case the line can be omitted completely; do not replace the line with whitespace. + +The first three lines are positional: + - **Line 1** [Optional]: `` A human-readable description of what this function does and, if needed, in which context it runs. Don't be too literal. + - **Line 2** [Required]: `@s = ` A human-readable or pseudocode description of the executing entity. May also be "unspecified" in case no executor was set intentionally. + - **Line 3** [Required]: `at ` A human-readable or pseudocode description of the location this function is run at. May also be "unspecified" in case no location was set intentionally. + +Additional lines may be present to indicate the context of the function. Each of the following may be specified multiple times, do **not** use a single line to specify multiple entries. + - `run from ` The full resource locator of a function that calls this function. Use of wildcards, e.g. `run from gm4:boats/*` is permitted. + - `scheduled from ` The full resource locator of a function that schedules this function. Use of wildcards, e.g. `run from gm4:boats/*` is permitted. + - `rewarded from ` The full resource locator of an advancement that rewards this function. Use of wildcards, e.g. `run from gm4:join/*` is permitted. + - `with $: ` The key of an nb tag used for the macro call of this function, as well as a description of the value the key holds. Do not specify this unless this function is a macro. Use of wildcards, e.g. `with $id_*: Set of 16 ids used to track runcows.` ### Inline comments Inline comments should be placed to partition code into logical sections and `#` should be followed by a space, e.g. From c31d8e955aff9264e1abed5752f38427003f377f Mon Sep 17 00:00:00 2001 From: Bloo Date: Tue, 10 Mar 2026 22:10:08 +0100 Subject: [PATCH 2/2] Add Note on Omitted Namespace --- docs/code-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/code-conventions.md b/docs/code-conventions.md index 8cb2b8952b..eb70301a8e 100644 --- a/docs/code-conventions.md +++ b/docs/code-conventions.md @@ -40,7 +40,7 @@ The first three lines are positional: - **Line 3** [Required]: `at ` A human-readable or pseudocode description of the location this function is run at. May also be "unspecified" in case no location was set intentionally. Additional lines may be present to indicate the context of the function. Each of the following may be specified multiple times, do **not** use a single line to specify multiple entries. - - `run from ` The full resource locator of a function that calls this function. Use of wildcards, e.g. `run from gm4:boats/*` is permitted. + - `run from ` The resource locator of a function that calls this function. Use of wildcards, e.g. `run from gm4:boats/*` is permitted. The namespace of the resource locator may be omitted, in which case the namespace of the current function is assumed. - `scheduled from ` The full resource locator of a function that schedules this function. Use of wildcards, e.g. `run from gm4:boats/*` is permitted. - `rewarded from ` The full resource locator of an advancement that rewards this function. Use of wildcards, e.g. `run from gm4:join/*` is permitted. - `with $: ` The key of an nb tag used for the macro call of this function, as well as a description of the value the key holds. Do not specify this unless this function is a macro. Use of wildcards, e.g. `with $id_*: Set of 16 ids used to track runcows.`