From 39bc3f587235515a20e90d5e524647e13119f84a Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Mon, 8 Apr 2024 21:19:24 +0200 Subject: [PATCH] Fix a few class documentation issues Fixed a few newline issues and made all notes, warnings and dangers (is that a word?) bold and partially italic. --- docs/docs/reference/storage.md | 2 +- src/classes/basemodule.gd | 2 +- src/classes/config.gd | 2 +- src/classes/loggerinstance.gd | 4 ++-- src/core.gd | 16 ++++++++-------- src/erm.gd | 28 ++++++++++++++-------------- src/logger.gd | 8 ++++---- src/misc.gd | 16 ++++++++-------- src/sms.gd | 18 +++++++++--------- src/storage.gd | 14 +++++++------- 10 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/docs/reference/storage.md b/docs/docs/reference/storage.md index 763f782..15ec647 100644 --- a/docs/docs/reference/storage.md +++ b/docs/docs/reference/storage.md @@ -41,7 +41,7 @@ Updates a storage key with the specified value. Deletes a storage key. ### *Dictionary* get_dict() Returns the `storage` `Dictionary`, useful for more advanced operations. \ -Changes are not reflected onto the `storage` dictionary though. To save changes through this module, \ +Changes are not reflected onto the `storage` dictionary though. To save changes through this module, pass your modified dictionary to `save_dict`. ### *bool* save_dict(*Dictionary* dict, *bool* sanity_check = *true*, *bool* fail_on_sanity_check = *false*, *bool* autosave = *true*) Saves a arbitrary dictionary as a `storage` dictionary with sanity checking (`sanity_check` and `fail_on_sanity_check`). diff --git a/src/classes/basemodule.gd b/src/classes/basemodule.gd index 640f054..65b865e 100644 --- a/src/classes/basemodule.gd +++ b/src/classes/basemodule.gd @@ -31,7 +31,7 @@ var loggeri: CoreLoggerInstance ## Marks a module as fully initialized and ready. **Don't forget to set this!** var initialized: bool = false -## CORE's replacement for [method Object._init] and [method Node._ready]. +## CORE's replacement for [method Object._init] and [method Node._ready].[br] ## It's [b]strongly[/b] recommended to initialize your module here or stuff might break. func _initialize() -> void: initialized = true ## Called when CORE is about to cleanup.[br] diff --git a/src/classes/config.gd b/src/classes/config.gd index 62e938b..5edbd68 100644 --- a/src/classes/config.gd +++ b/src/classes/config.gd @@ -14,7 +14,7 @@ class_name CoreConfiguration @export var headless: bool ## Allows debugging functionality if set to [code]true[/code], or not if set to [code]false[/code].[br] ## [br] -## Note: This will not enable the development mode automatically, only if you're developing on CORE itself. +## [b]Note: [i]This will not enable the development mode automatically, only if you're developing on CORE itself.[/i][/b] @export var debugging: bool ## Allows or disallows custom modules. @export var custom_modules: bool diff --git a/src/classes/loggerinstance.gd b/src/classes/loggerinstance.gd index e80fa0e..3c5479f 100644 --- a/src/classes/loggerinstance.gd +++ b/src/classes/loggerinstance.gd @@ -44,6 +44,6 @@ func info(message: String) -> void: logger.info(origin, message) func warn(message: String) -> void: logger.warn(origin, message) ## Prints an error message. func error(message: String) -> void: logger.error(origin, message) -## Handles crashes. Will terminate your game/application immediately. -## Note: Using the [code]await[/code] keyword is required for this function. +## Handles crashes. Will terminate your game/application immediately.[br] +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b] func crash(message: String) -> void: await logger.crash(origin, message) diff --git a/src/core.gd b/src/core.gd index 22d4741..3878cb4 100644 --- a/src/core.gd +++ b/src/core.gd @@ -51,13 +51,13 @@ var storage: CoreBaseModule # /etc/ ## Stores the path to CORE's installation directory.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var basepath: String ## Contains a list of all loaded custom modules.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var custom_modules: Dictionary = {} ## Contains the node holding all custom modules as children.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var custom_modules_node: Node # +++ initialization +++ @@ -72,14 +72,14 @@ func _init(new_config: CoreConfiguration = CoreConfiguration.new()) -> void: apply_configuration() ## Handles the initialization part. Injects the builtin modules into the SceneTree and makes sure custom modules can be loaded properly.[br] -## Danger: Don't call this. +## [b]Danger: [i]Don't call this.[/i][/b] func _ready() -> void: inject_modules() custom_modules_node.name = "Custom Modules" add_child(custom_modules_node) ## Initializes all built-in modules during the preinitialization phase.[br] -## Danger: Don't call this. +## [b]Danger: [i]Don't call this.[/i][/b] func initialize_modules() -> void: for module in modules: set(module, CoreBaseModule.new()) @@ -90,7 +90,7 @@ func initialize_modules() -> void: get(module)._initialize() ## Injects CORE's builtin modules into the SceneTree.[br] -## Danger: Don't call this. +## [b]Danger: [i]Don't call this.[/i][/b] func inject_modules() -> void: for module in modules: add_child(get(module)) ## Waits for all modules to fully initialize.[br] @@ -183,7 +183,7 @@ func reload_configuration(new_config: CoreConfiguration = CoreConfiguration.new( if initialized: apply_configuration() ## Applies the a configuration.[br] -## Danger: Don't call this. +## [b]Danger: [i]Don't call this.[/i][/b] func apply_configuration() -> void: logger.verbf("core", "Applying configuration") if is_devmode(): logger.warnf("core", "The CORE Framework is in development mode. Here be dragons!") @@ -271,7 +271,7 @@ func get_version_semantic() -> Array[int]: return [version_version, version_type_int, version_typerelease] ## Determines CORE's installation/base path.[br] -## Danger: Do not call. +## [b]Danger: [i]Don't call this.[/i][/b] func determine_basepath() -> bool: if FileAccess.file_exists("res://.corebasepath"): basepath = "res://" diff --git a/src/erm.gd b/src/erm.gd index ad0fcfb..adeeb10 100644 --- a/src/erm.gd +++ b/src/erm.gd @@ -19,13 +19,13 @@ extends CoreBaseModule ## Contains a list of all queued downloads.[br] -## Danger: Do not modify this. +## [b]Danger: [i]Don't modify this[/i][/b]. var list_queue: Dictionary = {} ## Contains a list of all active downloads.[br] -## Danger: Do not modify this. +## [b]Danger: [i]Don't modify this[/i][/b]. var list_active: Dictionary = {} ## Contains a liust of all completed downloads.[br] -## Danger: Do not modify this. +## [b]Danger: [i]Don't modify this[/i][/b]. var list_complete: Dictionary = {} ## Determines how unsecure requests should be handled. @@ -44,7 +44,7 @@ func _cleanup() -> void: # +++ methods that do the heavily lifting +++ ## Requests a file from the internet.[br] ## [br] -## The returned [code]Dictionary[/code] has the following structure (example):[br] +## The returned [code]Dictionary[/code] has the following structure (example): ## [codeblock] ## { "result": 0, "http_code": 200, "headers": [ "Server": "nginx" ], "body": [], "body_utf8": [] } ## ^ ^ ^ ^ ^ @@ -54,8 +54,8 @@ func _cleanup() -> void: ## | | ------------------------------------------------------ A array of headers ## | ---------------------------------------------------------------------- The HTTP response code ## ------------------------------------------------------------------------------------ Equal to @GlobalScope.Error. If not 0/Error.OK = the request failed -## [/codeblock][br] -## Note: Using the [code]await[/code] keyword is required for this function. +## [/codeblock] +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b] func awaited_request(url: String, parse_utf8: bool, method: HTTPClient.Method = HTTPClient.Method.METHOD_GET, headers: PackedStringArray = PackedStringArray([]), data: String = "") -> Dictionary: logger.verbf("erm", "Creating awaited request") if !await is_url_allowed(url): return {} @@ -71,7 +71,7 @@ func awaited_request(url: String, parse_utf8: bool, method: HTTPClient.Method = ## [br] ## Returns [code]null[/code] on error. To ignore HTTP errors (ie. non-200 statuses) set [code]ignore_http_code[/code] to [code]true[/code].[br] ## Returns a UTF-8 string with [code]return_utf8[/code] turned on, returns bytes when turned off.[br] -## Note: Using the [code]await[/code] keyword is required for this function. +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b] func oneline_awaited_request(url: String, return_utf8: bool = true, ignore_http_code: bool = false, method: HTTPClient.Method = HTTPClient.Method.METHOD_GET, headers: PackedStringArray = PackedStringArray([]), data: String = "") -> Variant: var dldata: Dictionary = await awaited_request(url, return_utf8, method, headers, data) if dldata == {}: return null @@ -93,9 +93,8 @@ func oneline_awaited_request(url: String, return_utf8: bool = true, ignore_http_ ## | | ------------------------------------------------------ A array of headers ## | ---------------------------------------------------------------------- The HTTP response code ## ------------------------------------------------------------------------------------ Equal to @GlobalScope.Error. If not 0/Error.OK = the request failed -## [/codeblock][br] -## Note: Using the [code]await[/code] keyword is required for this function. - +## [/codeblock] +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b] func batch_awaited_request(urls: PackedStringArray, parse_utf8: bool, method: HTTPClient.Method = HTTPClient.Method.METHOD_GET, headers: PackedStringArray = PackedStringArray([]), data: String = "") -> Array[Dictionary]: logger.verbf("erm", "Creating " + str(urls.size()) + " awaited request(s)") var dldata: Array[Dictionary] = [] @@ -108,6 +107,7 @@ func batch_awaited_request(urls: PackedStringArray, parse_utf8: bool, method: HT list_complete.erase(id) return dldata +## Internal function, do not call func _batch_awaited_request(url: String, parse_utf8: bool, method: HTTPClient.Method = HTTPClient.Method.METHOD_GET, headers: PackedStringArray = PackedStringArray([]), data: String = "") -> int: var id: int = create_request(url, method, headers, data) start_request(id, parse_utf8) @@ -117,7 +117,7 @@ func _batch_awaited_request(url: String, parse_utf8: bool, method: HTTPClient.Me # +++ internal +++ ## Returns a new download id.[br] -## Danger: Don't call this. +## [b]Danger: [i]Don't call this.[/i][/b] func generate_id() -> int: var id = randi() if list_queue.has(id) or list_active.has(id): @@ -127,7 +127,7 @@ func generate_id() -> int: return id ## Creates a new request and stores it in the queue. Returns the download id.[br] -## Warning: You'll probably not need this. Only use this function when implementing your own downloading method. +## [b]Warning: [i]You'll probably not need this. Only use this function when implementing your own downloading method.[/i][/b] func create_request(url: String, method: HTTPClient.Method = HTTPClient.Method.METHOD_GET, headers: PackedStringArray = PackedStringArray([]), body: String = "") -> int: logger.verbf("erm", "Creating new request\n-> URL: " + url + "\n-> Method: " + str(method) + "\nHeaders: " + str(headers.size()) + "\nBody size: " + str(body.length()) + " Characters") var id = generate_id() @@ -135,8 +135,8 @@ func create_request(url: String, method: HTTPClient.Method = HTTPClient.Method.M return id ## Configures and starts a queued request.[br] -## Note: Using the [code]await[/code] keyword is required for this function.[br] -## Warning: You'll probably not need this. Only use this function when implementing your own downloading method. +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b][br] +## [b]Warning: [i]You'll probably not need this. Only use this function when implementing your own downloading method.[/i][/b] func start_request(id: int, parse_utf8: bool) -> void: logger.verbf("erm", "Starting request " + str(id)) list_active.merge({ id: list_queue[id] }) diff --git a/src/logger.gd b/src/logger.gd index a8f3c02..a081bf2 100644 --- a/src/logger.gd +++ b/src/logger.gd @@ -45,7 +45,7 @@ func _pull_config() -> void: # +++ logging +++ ## The main logging function that does the heavy lifting.[br] -## Danger: Do not call. +## [b]Danger: [i]Don't call this.[/i][/b] func _log(level: CoreTypes.LoggerLevel, origin: String, message: String) -> void: if !is_level_allowed(level): emit_signal("log_event", false, level, origin, message, "") @@ -99,9 +99,9 @@ func info(origin: String, message: String) -> void: _log(CoreTypes.LoggerLevel.I func warn(origin: String, message: String) -> void: _log(CoreTypes.LoggerLevel.WARN, origin, message) ## Prints an error log message. func error(origin: String, message: String) -> void: _log(CoreTypes.LoggerLevel.ERROR, origin, message) -## Handles crashes. Will terminate your game/application immediately. -## Note: Using the [code]await[/code] keyword is required for this function. -## Danger: Don't set [code]framework_crash[/code] to [code]true[/code], thanks! +## Handles crashes. Will terminate your game/application immediately.[br] +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b][br] +## [b]Danger: [i]Don't set [code]framework_crash[/code] to [code]true[/code], thanks![/i][/b] func crash(origin: String, message: String, framework_crash: bool = false) -> void: # Collect information var stack: Array[Dictionary] = get_stack() diff --git a/src/misc.gd b/src/misc.gd index e8b2af3..3bb6513 100644 --- a/src/misc.gd +++ b/src/misc.gd @@ -63,10 +63,10 @@ func gib2mib(gib: float, flatten: bool = true) -> float: ## var logger: CoreLoggerInstance = core.logger.get_instance("some/script.gd") ## ## func _ready() -> void: -## var array: Array[String] = ["Apples", "Bananas", "Oranges"] -## -## logger.info(misc.format_stringarray(array)) -## logger.info(misc.format_stringarray(array, "[b]", "[/b]")) +## var array: Array[String] = ["Apples", "Bananas", "Oranges"] +## +## logger.info(misc.format_stringarray(array)) +## logger.info(misc.format_stringarray(array, "[b]", "[/b]")) ## [/codeblock] func format_stringarray(array: Array[String], item_before: String = "", item_after: String = "", separator_list: String = ", ", separator_final: String = " & ") -> String: var output: String = "" @@ -120,14 +120,14 @@ func stringarray_to_array(array: Array[String]) -> Array: ## var misc: CoreBaseModule = core.misc ## ## func _ready() -> void: -## position = misc.center_object(get_parent().size, size) +## position = misc.center_object(get_parent().size, size) ## [/codeblock] func get_center(parent_size: Vector2, child_size: Vector2) -> Vector2: return Vector2(parent_size.x/2-child_size.x/2, parent_size.y/2-child_size.y/2) -## Makes sure for all log messages to be flushed and that CORE is correctly cleaned up. -## Using [method SceneTree.quit] directly may cause various issues. -## Note: Using the [code]await[/code] keyword is required for this function. +## Makes sure for all log messages to be flushed and that CORE is correctly cleaned up.[br] +## Using [method SceneTree.quit] directly may cause various issues.[br] +## [b]Note: [i]Using the [code]await[/code] keyword is required for this function.[/i][/b] func quit_safely(exitcode: int = 0) -> void: logger.infof("misc", "Shutting down (code " + str(exitcode) + ")") await get_tree().create_timer(0.25).timeout diff --git a/src/sms.gd b/src/sms.gd index ff6b92d..a05d659 100644 --- a/src/sms.gd +++ b/src/sms.gd @@ -23,23 +23,23 @@ extends CoreBaseModule ## Used internally for adding, managing and removing scene collections. const scene_nodes: Array[String] = [ "debug", "cutscene", "menu", "main", "background" ] ## The 'debug' scene collection.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_debug: Node = Node.new() ## The 'cutscene' scene collection.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_cutscene: Node = Node.new() ## The 'menu' scene collection.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_menu: Node = Node.new() ## The 'main' scene collection.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_main: Node = Node.new() ## The 'background' scene collection.[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_background: Node = Node.new() ## A list of all loaded scenes[br] -## Danger: Don't modify this. +## [b]Danger: [i]Don't modify this.[/i][/b] var scenes: Dictionary = {} # +++ module +++ @@ -87,8 +87,8 @@ func add_scene(sname: String, sclass: Node, type: CoreTypes.SceneType) -> bool: scenes.merge({ sname: { "type": type, "class": sclass } }) return true -## Removes a scene from some scene collection. -## Danger: Don't set [code]force_remove[/code] to [code]true[/code], thanks! +## Removes a scene from some scene collection.[br] +## [b]Danger: [i]Don't set [code]force_remove[/code] to [code]true[/code], thanks![/i][/b] func remove_scene(sname: String, force_remove: bool = false) -> bool: if core.config.headless and !force_remove: return false if force_remove: await logger.crashf("sms", "force_remove = true is not allowed", true) @@ -134,7 +134,7 @@ func get_scene(sname: String) -> Node: ## Returns a scene collection node.[br] ## Useful if you want to change a child's index.[br] -## Danger: Don't change any properties of the scene collection or free it, otherwise you may cause breakage. +## [b]Danger: [i]Don't change any properties of the scene collection or free it, otherwise you may cause breakage.[/i][/b] func get_scene_collection(type: CoreTypes.SceneType) -> Node: if core.config.headless: return null match(type): diff --git a/src/storage.gd b/src/storage.gd index 07f87c5..025c607 100644 --- a/src/storage.gd +++ b/src/storage.gd @@ -20,14 +20,14 @@ extends CoreBaseModule ## ## Allows you to read and write configuration files with ease, without any headaches. -## Indicates if a storage file is currently open. -## Danger: Don't modify this. +## Indicates if a storage file is currently open.[br] +## [b]Danger: [i]Don't modify this.[/i][/b] var is_open: bool = false -## The parsed data inside the storage file. -## Danger: Don't modify this. +## The parsed data inside the storage file.[br] +## [b]Danger: [i]Don't modify this.[/i][/b] var storage: Dictionary = {} -## The location of the storage file. -## Danger: Don't modify this. +## The location of the storage file.[br] +## [b]Danger: [i]Don't modify this.[/i][/b] var storage_location: String = "" # +++ file management +++ @@ -137,7 +137,7 @@ func del_key(key: String, autosave: bool = true) -> bool: return true ## Returns the [param storage] [class Dictionary], useful for more advanced operations.[br] -## Changes are not reflected onto the [param storage] though. To save changes through this module,[br] +## Changes are not reflected onto the [param storage] though. To save changes through this module, ## pass your modified [class Dictionary to [method safe_dict]. func get_dict() -> Dictionary: if !is_open: