Timer: Document init and follow conventions in public api

This documents the full init function and adds declarations for every
variable used for the api. (Work towards #5)

Other functions are not yet documented.

Some objective names where renamed to follow new conventions. (Work
towards #4)

.vscode/settings.json

@@ -18,19 +18,33 @@
 	"datapack.lint.nameOfNbtCompoundTagKeys": null, //["warning", "camelCase"],
 	"datapack.lint.nameOfObjectives": [
 		"warning",
-		{
-			"label": "namespace.snake_case",
-			"parts": [ "snake_case", "snake_case" ],
-			"sep": "."
-		}
+		[
+			{
+				"label": "bingo.snake_case",
+				"parts": [ "/bingo/", "snake_case" ],
+				"sep": "."
+			},
+			{
+				"label": "author.name_space.snake_case",
+				"parts": [ "snake_case", "snake_case", "snake_case" ],
+				"sep": "."
+			}
+		]
 	],
 	"datapack.lint.nameOfTags": [
 		"warning",
-		{
-			"label": "namespace.snake_case",
-			"parts": [ "snake_case", "snake_case" ],
-			"sep": "."
-		}
+		[
+			{
+				"label": "bingo.snake_case",
+				"parts": [ "/bingo/", "snake_case" ],
+				"sep": "."
+			},
+			{
+				"label": "author.name_space.snake_case",
+				"parts": [ "snake_case", "snake_case", "snake_case" ],
+				"sep": "."
+			}
+		]
 	],
 	"datapack.lint.nameOfTeams": [
 		"warning",

data/neun_einser.timer/functions/internal/init.mcfunction

@@ -1,7 +1,106 @@
+#> neun_einser.timer:internal/init
+#
+# Declares scoreboard and storage 
+#
+# @handles #minecraft:load
+# @within tag/function minecraft:load
+
+#>
+# Storage containing the time since start in some default formats
+#
+# Available are:
+# hh:mm:ss.s (.s means fractions of a second, 1 - 3 digits depending on the value)
+# hh:mm:ss
+# hh:mm
+#
+# All of these are keys in this storage and contain a text component meant for
+# use like this:
+#
+# {"storage": "neun_einser.timer:display", "nbt": "hh:mm:ss.s", "interpret":
+# true }
+#
+# This accounts for appending 0s where neccesary and only contains components
+# > 0.
+#
+# Examples hh:mm:ss might output:
+# 1:02:03 (for 1h 2m 3s)
+# 1:15:21 (for 1h 15m 21s)
+# 1:00:00 (for 1h 0m 0s)
+# 1:02 (for 1m 2s)
+# 1 (for 1s)
+#
+# For hh:mm:ss.s, seconds is always set. Examples:
+# 0.5 (for 0s, 500 millis)
+# 0.023 (for 0s, 23 millis)
+# 1:15.31 (for 1m 15s 310 millis)
+#
+# @api
 #declare storage neun_einser.timer:display
 
-scoreboard objectives add timer_main dummy "Minecraft Timer"
-scoreboard objectives add timer_const dummy "Constant Table"
-scoreboard players set 60 timer_const 60
+#>
+# This objective contains the current time.
+#
+# $raw contains the raw time with the chosen percision (example: if the timer
+# was started with start/seconds, this is the time in seconds since the start.)
+#
+# $millis is between 0 and 999 and contains the millisecond part
+# $seconds is between 0 and 59 and contains the second part
+# $minutes is between 0 and 59 and contains the minute part
+# $hours is 0 or higher and contains the hour part.
+#
+# @api
+scoreboard objectives add 91.timer.main dummy
+#>
+# This score holder contains the raw time with the selected percision.
+#
+# In particular this means:
+# * Seconds since start, when having used neun_einser.timer:start/second
+# * Deciseconds since start, when having used
+#   neun_einser.timer:start/tenth_of_second
+# * Centiseconds since start, when using
+#   neun_einser.timer:start/hundreth_of_second
+# * Milliseconds since start when having used neun_einser.timer:start/millis
+#
+# @api
+#declare score_holder $raw
+#>
+# This score holder contains the millisecond part.
+#
+# This is always between 0 and 999 (inclusive)
+#
+# @api
+#declare score_holder $millis
+#>
+# This score holder contains the second part.
+#
+# This is always between 0 and 59 (inclusive)
+#
+# @api
+#declare score_holder $seconds
+#>
+# This score holder contains the minute part.
+#
+# This is always between 0 and 59 (inclusive)
+#
+# @api
+#declare score_holder $minutes
+#>
+# This score holder contains the hour part.
+#
+# This score is uncapped.
+#
+# @api
+#declare score_holder $hours
+
+#>
+# This scoreboard is used to store constant values.
+#
+# @internal
+scoreboard objectives add 91.timer.const dummy
+
+#>
+# @internal
+#declare score_holder 60
+scoreboard players set 60 91.timer.const 60
 
 data merge storage neun_einser.timer:display {"hh:mm:ss.s": '[{"storage": "neun_einser.timer:display", "nbt": "internal.hours", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.minutes", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.seconds", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.millis", "interpret": true}]', "hh:mm:ss": '[{"storage": "neun_einser.timer:display", "nbt": "internal.hours", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.minutes", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.seconds", "interpret": true}]', "hh:mm": '[{"storage": "neun_einser.timer:display", "nbt": "internal.hours", "interpret": true}, {"storage": "neun_einser.timer:display", "nbt": "internal.minutes", "interpret": true}]'}

data/neun_einser.timer/functions/internal/prevent_overflow.mcfunction

@@ -1,8 +1,8 @@
-scoreboard players remove $start timer_main 5000000
-scoreboard players remove $raw timer_main 5000000
+scoreboard players remove $start 91.timer.main 5000000
+scoreboard players remove $raw 91.timer.main 5000000
 worldborder add -5000000
 
-execute if score $blocks_per_second timer_main matches 1000 run worldborder add 7500000 7500
-execute if score $blocks_per_second timer_main matches 100 run worldborder add 7500000 75000
-execute if score $blocks_per_second timer_main matches 10 run worldborder add 7500000 750000
-execute if score $blocks_per_second timer_main matches 1 run worldborder add 7500000 7500000
+execute if score $blocks_per_second 91.timer.main matches 1000 run worldborder add 7500000 7500
+execute if score $blocks_per_second 91.timer.main matches 100 run worldborder add 7500000 75000
+execute if score $blocks_per_second 91.timer.main matches 10 run worldborder add 7500000 750000
+execute if score $blocks_per_second 91.timer.main matches 1 run worldborder add 7500000 7500000

data/neun_einser.timer/functions/internal/read_raw.mcfunction

@@ -1,4 +1,4 @@
-execute store result score $raw timer_main run worldborder get
-execute if score $raw timer_main matches 55000000.. run function neun_einser.timer:internal/prevent_overflow
+execute store result score $raw 91.timer.main run worldborder get
+execute if score $raw 91.timer.main matches 55000000.. run function neun_einser.timer:internal/prevent_overflow
 
-scoreboard players operation $raw timer_main -= $start timer_main
+scoreboard players operation $raw 91.timer.main -= $start 91.timer.main

data/neun_einser.timer/functions/pause.mcfunction

@@ -1,3 +1,3 @@
 function neun_einser.timer:internal/read_raw
-scoreboard players operation $start timer_main -= $raw timer_main
+scoreboard players operation $start 91.timer.main -= $raw 91.timer.main
 worldborder set 10000000

data/neun_einser.timer/functions/read.mcfunction

@@ -1,13 +1,13 @@
 function neun_einser.timer:internal/read_raw
 
-scoreboard players operation $millis timer_main = $raw timer_main
-scoreboard players operation $seconds timer_main = $millis timer_main
-scoreboard players operation $seconds timer_main /= $blocks_per_second timer_main
-scoreboard players operation $minutes timer_main = $seconds timer_main
-scoreboard players operation $minutes timer_main /= 60 timer_const
-scoreboard players operation $hours timer_main = $minutes timer_main
-scoreboard players operation $hours timer_main /= 60 timer_const
+scoreboard players operation $millis 91.timer.main = $raw 91.timer.main
+scoreboard players operation $seconds 91.timer.main = $millis 91.timer.main
+scoreboard players operation $seconds 91.timer.main /= $blocks_per_second 91.timer.main
+scoreboard players operation $minutes 91.timer.main = $seconds 91.timer.main
+scoreboard players operation $minutes 91.timer.main /= 60 91.timer.const
+scoreboard players operation $hours 91.timer.main = $minutes 91.timer.main
+scoreboard players operation $hours 91.timer.main /= 60 91.timer.const
 
-scoreboard players operation $millis timer_main %= $blocks_per_second timer_main
-scoreboard players operation $seconds timer_main %= 60 timer_const
-scoreboard players operation $minutes timer_main %= 60 timer_const
+scoreboard players operation $millis 91.timer.main %= $blocks_per_second 91.timer.main
+scoreboard players operation $seconds 91.timer.main %= 60 91.timer.const
+scoreboard players operation $minutes 91.timer.main %= 60 91.timer.const

data/neun_einser.timer/functions/resume.mcfunction

@@ -1,4 +1,4 @@
-execute if score $blocks_per_second timer_main matches 1000 run worldborder set 50000000 50000
-execute if score $blocks_per_second timer_main matches 100 run worldborder set 50000000 500000
-execute if score $blocks_per_second timer_main matches 10 run worldborder set 50000000 5000000
-execute if score $blocks_per_second timer_main matches 1 run worldborder set 50000000 50000000
+execute if score $blocks_per_second 91.timer.main matches 1000 run worldborder set 50000000 50000
+execute if score $blocks_per_second 91.timer.main matches 100 run worldborder set 50000000 500000
+execute if score $blocks_per_second 91.timer.main matches 10 run worldborder set 50000000 5000000
+execute if score $blocks_per_second 91.timer.main matches 1 run worldborder set 50000000 50000000

data/neun_einser.timer/functions/start/hundredth_of_second.mcfunction

@@ -1,4 +1,4 @@
 worldborder set 50000000
-scoreboard players set $start timer_main 50000000
+scoreboard players set $start 91.timer.main 50000000
 worldborder set 60000000 100000
-scoreboard players set $blocks_per_second timer_main 100
+scoreboard players set $blocks_per_second 91.timer.main 100

data/neun_einser.timer/functions/start/millis.mcfunction

@@ -1,4 +1,4 @@
 worldborder set 50000000
-scoreboard players set $start timer_main 50000000
+scoreboard players set $start 91.timer.main 50000000
 worldborder set 60000000 10000
-scoreboard players set $blocks_per_second timer_main 1000
+scoreboard players set $blocks_per_second 91.timer.main 1000

data/neun_einser.timer/functions/start/second.mcfunction

@@ -1,4 +1,4 @@
 worldborder set 50000000
-scoreboard players set $start timer_main 50000000
+scoreboard players set $start 91.timer.main 50000000
 worldborder set 60000000 10000000
-scoreboard players set $blocks_per_second timer_main 1
+scoreboard players set $blocks_per_second 91.timer.main 1

data/neun_einser.timer/functions/start/tenth_of_second.mcfunction

@@ -1,4 +1,4 @@
 worldborder set 50000000
-scoreboard players set $start timer_main 50000000
+scoreboard players set $start 91.timer.main 50000000
 worldborder set 60000000 10000000
-scoreboard players set $blocks_per_second timer_main 10
+scoreboard players set $blocks_per_second 91.timer.main 10

data/neun_einser.timer/functions/store_current_time.mcfunction

@@ -1,6 +1,6 @@
 function neun_einser.timer:read
 data remove storage neun_einser.timer:display internal
 
-execute if score $hours timer_main matches 1.. run function neun_einser.timer:internal/display/add_hours
-execute if score $hours timer_main matches 0 if score $minutes timer_main matches 1.. run function neun_einser.timer:internal/display/add_minutes
-execute if score $hours timer_main matches 0 if score $minutes timer_main matches 0 run function neun_einser.timer:internal/display/add_seconds
+execute if score $hours 91.timer.main matches 1.. run function neun_einser.timer:internal/display/add_hours
+execute if score $hours 91.timer.main matches 0 if score $minutes 91.timer.main matches 1.. run function neun_einser.timer:internal/display/add_minutes
+execute if score $hours 91.timer.main matches 0 if score $minutes 91.timer.main matches 0 run function neun_einser.timer:internal/display/add_seconds