From 97703eac04608f112acabcfa398dead8be531d70 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Mon, 15 Apr 2024 00:07:25 +0200 Subject: [PATCH] Purge online and in-editor documentation for internal methods & vars --- docs/docs/reference/core.md | 46 ---------------------------------- docs/docs/reference/erm.md | 24 ------------------ docs/docs/reference/logger.md | 11 -------- docs/docs/reference/sms.md | 32 ----------------------- docs/docs/reference/storage.md | 10 -------- src/core.gd | 29 ++++++++------------- src/erm.gd | 14 ++++------- src/logger.gd | 7 ++---- src/sms.gd | 14 ++--------- src/storage.gd | 8 +++--- 10 files changed, 22 insertions(+), 173 deletions(-) diff --git a/docs/docs/reference/core.md b/docs/docs/reference/core.md index 7482bc6..9751d60 100644 --- a/docs/docs/reference/core.md +++ b/docs/docs/reference/core.md @@ -36,22 +36,6 @@ Used internally for loading, managing and unloading modules. Do not modify this. ::: Stores the path to CORE's installation directory. -### *Dictionary* cleanup_hooks = *{}* -:::danger[Don't modify] -Do not modify this. -::: -Contains a list of all registered cleanup hooks. -### *Dictionary* custom_modules = *{}* -### *void* _ready() -:::danger[Don't modify] -Do not modify this. -::: -Contains a list of all loaded custom modules. -### *Node* custom_modules_node -:::danger[Don't modify] -Do not modify this. -::: -Contains the node holding all custom modules as children. ## Functions ### *void* _init(*CoreConfiguration* new_config) @@ -59,26 +43,6 @@ Contains the node holding all custom modules as children. Do not call this (except you're using `Core.new()`). ::: Handles the preinitialization part. Does stuff like checking the engine version, loading the config and loading all modules into memory. -### *void* _ready() -:::danger[Don't call] -Do not call this. -::: -Handles the initialization part. Injects the builtin modules into the SceneTree and makes sure custom modules can be loaded properly. \ -### *void* initialize_modules() -:::danger[Don't call] -Do not call this. -::: -Initializes all built-in modules during the preinitialization phase. -### *void* inject_modules() -:::danger[Don't call] -Do not call this. -::: -Injects CORE's built-in modules into the SceneTree. -### *void* initialize_scheduler() -:::danger[Don't call] -Do not call this. -::: -Initializes the framework scheduler. ### *void* complete_init(*bool* no_success_message = *false*) Waits for all built-in and custom modules to fully initialize. \ \ @@ -93,11 +57,6 @@ Returns a registered custom module. \ Please note that you can't get CORE's built-in modules with this function. ### *void* reload_configuration(*CoreConfiguration* new_config = *CoreConfiguration.new()*) Loads a (new) configuration object and applies it to all modules. -### *void* apply_configuration() -:::danger[Don't call] -Do not call this. -::: -Applies the a configuration. ### *void* cleanup() Makes sure that CORE does not leak memory on shutdown/unload. \ Unloads all custom modules, built-in modules, frees any of CORE's classes and lastly itself. \ @@ -132,11 +91,6 @@ You can use the following placeholders: Returns if custom module support is enabled ### *Array[int]* get_version_semantic() Returns the CORE version in the semantic versioning scheme. The first integer contains the version number, the second integer contains the version type (`0` for alpha, `1` for beta, `2` for rc and `3` for release) and the last integer contains the version type number. -### *bool* determine_basepath() -:::danger[Don't call] -Do not call this. -::: -Determines CORE's installation/base path. ### *void* quit_safely(*int* exitcode = *0*) :::note[Awaiting required] Using the `await` keyword is required for this function. diff --git a/docs/docs/reference/erm.md b/docs/docs/reference/erm.md index bbafac0..587e9a8 100644 --- a/docs/docs/reference/erm.md +++ b/docs/docs/reference/erm.md @@ -7,25 +7,6 @@ description: Allows for awaited, batched and oneline requests. Makes it easy to download files off the internet and communicate with HTTP servers. -## Variables -### *Dictionary* list_queue = *{}* -:::danger[Don't modify] -Do not modify this. -::: -Contains a list of all queued downloads. - -### *Dictionary* list_active = *{}* -:::danger[Don't modify] -Do not modify this. -::: -Contains a list of all active downloads. - -### *Dictionary* list_complete = *{}* -:::danger[Don't modify] -Do not modify this. -::: -Contains a list of all completed downloads. - ## Functions ### *Dictionary* awaited_request(*String* url, *bool* parse_utf8, *HTTPClient.Method* method = *HTTPClient.Method.METHOD_GET*, *PackedStringArray* headers = *PackedStringArray([])*, *String* data = *""*) :::note[Awaiting required] @@ -70,11 +51,6 @@ The returned `Dictionary`s have the following structure (example): | ---------------------------------------------------------------------- The HTTP response code ------------------------------------------------------------------------------------ Equal to @GlobalScope.Error. If not 0/Error.OK = the request failed ``` -### *int* generate_id() -:::danger[Don't call] -Do not call this. -::: -Returns a new download id. ### *int* create_request(*String* , *HTTPClient.Method* method = *HTTPClient.Method.METHOD_GET*, *PackedStringArray* headers = *PackedStringArray([])*, *String* body = *""*) :::warning You'll probably not need this. Only use this function when implementing your own downloading method. diff --git a/docs/docs/reference/logger.md b/docs/docs/reference/logger.md index d296683..12039d6 100644 --- a/docs/docs/reference/logger.md +++ b/docs/docs/reference/logger.md @@ -15,22 +15,11 @@ Emitted on any log call, permitted or not. \ **format** is set to `""` when **allowed** is set `false`. ## Variables -### *Array[CoreLoggerInstance]* instances = *[]* -:::danger[Don't call] -Do not call this. -::: -Keeps track of all logger instances. -Unused instances will be cleaned periodically. ### *bool* verbose_mode = *false* Used to determine if running in verbose/command line mode. Makes diagnostic log messages display correctly (workaround for Godot's ANSI true color limitation). ## Functions -### *void* _log(*CoreTypes.LoggerLevel* level, *String* origin, *String* message) -:::danger[Don't call] -Do not call this. -::: -The main logging function that does the heavy lifting. ### *void* diag(*String* origin, *String* message) Prints a diagnostic message. ### *void* verb(*String* origin, *String* message) diff --git a/docs/docs/reference/sms.md b/docs/docs/reference/sms.md index b5bc182..21a4fd4 100644 --- a/docs/docs/reference/sms.md +++ b/docs/docs/reference/sms.md @@ -11,38 +11,6 @@ Allows for organized scene management, making development much faster. ## *Array[String]* scene_nodes = *[ "debug", "cutscene", "menu", "main", "background" ]* Used internally for adding, managing and removing scene collections. -## Variables -## *Node* scenes_debug = *Node.new()* -:::danger[Don't modify] -Do not modify this. -::: -The 'debug' scene collection. -## *Node* scenes_cutscene = *Node.new()* -:::danger[Don't modify] -Do not modify this. -::: -The 'cutscene' scene collection. -## *Node* scenes_menu = *Node.new()* -:::danger[Don't modify] -Do not modify this. -::: -The 'menu' scene collection. -## *Node* scenes_main = *Node.new()* -:::danger[Don't modify] -Do not modify this. -::: -The 'main' scene collection. -## *Node* scenes_background = *Node.new()* -:::danger[Don't modify] -Do not modify this. -::: -The 'background' scene collection. -## *Dictionary* scenes = *{}* -:::danger[Don't modify] -Do not modify this. -::: -A list of all loaded scenes - ## Functions ### *bool* add_scene(*String* scene_name, *Node* scene_class, *CoreTypes.SceneType* scene_type) Adds a scene to some scene collection. diff --git a/docs/docs/reference/storage.md b/docs/docs/reference/storage.md index 15ec647..297ec8d 100644 --- a/docs/docs/reference/storage.md +++ b/docs/docs/reference/storage.md @@ -13,16 +13,6 @@ Allows you to write configuration files with ease, without any headaches. Do not modify this. ::: Indicates if a storage file is currently open. -### *Dictionary* storage = *{}* -:::danger[Don't modify] -Do not modify this. -::: -The parsed data inside the storage file. -### *String* storage_location = *""* -:::danger[Don't modify] -Do not modify this. -::: -The location of the storage file. ## Functions ### *bool* open_storage(*String* location, *bool* create_new = *true*, *bool* sanity_check = *true*, *bool* fail_on_sanity_check = *false*) diff --git a/src/core.gd b/src/core.gd index 8728b9f..37c6a6c 100644 --- a/src/core.gd +++ b/src/core.gd @@ -57,17 +57,13 @@ var storage: CoreBaseModule ## Stores the path to CORE's installation directory.[br] ## [b]Danger: [i]Don't modify this.[/i][/b] var basepath: String -## Contains a list of all registered cleanup hooks.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# Contains a list of all registered cleanup hooks. var cleanup_hooks: Dictionary = {} -## Contains a list of all loaded custom modules.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# Contains a list of all loaded custom modules. var custom_modules: Dictionary = {} -## Contains the node holding all custom modules as children.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# Contains the node holding all custom modules as children. var custom_modules_node: Node -## The CORE Object's logger instance. -## [b]Danger: [i]Don't modify this.[/i][/b] +# The CORE Object's logger instance. var loggeri: CoreLoggerInstance # +++ initialization +++ @@ -89,8 +85,7 @@ func _ready() -> void: add_child(scheduler) get_tree().auto_accept_quit = false -## Initializes all built-in modules during the preinitialization phase.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# Initializes all built-in modules during the preinitialization phase. func initialize_modules() -> void: for module in modules: set(module, CoreBaseModule.new()) @@ -100,12 +95,10 @@ func initialize_modules() -> void: get(module).loggeri = logger.get_instance(basepath.replace("res://", "") + "src/" + module + ".gd", get(module)) get(module)._initialize() -## Injects CORE's builtin modules into the SceneTree.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# Injects CORE's builtin modules into the SceneTree. func inject_modules() -> void: for module in modules: add_child(get(module)) -## Initializes the framework scheduler. -## [b]Danger: [i]Don't call this.[/i][/b] +# Initializes the framework scheduler. func initialize_scheduler() -> void: scheduler = Timer.new() scheduler.name = "Scheduler" @@ -163,8 +156,7 @@ func reload_configuration(new_config: CoreConfiguration = CoreConfiguration.new( if initialized: loggeri.verb("Overrode configuration (development mode)") if initialized: apply_configuration() -## Applies the a configuration.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# Applies a new configuration. func apply_configuration() -> void: if loggeri != null: loggeri.verb("Applying configuration") if is_devmode() and loggeri != null: loggeri.warn("The CORE Framework is in development mode. Here be dragons!") @@ -356,8 +348,7 @@ func get_version_semantic() -> Array[int]: CoreTypes.VersionType.ALPHA: version_type_int = 0 return [version_version, version_type_int, version_typerelease] -## Determines CORE's installation/base path.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# Determines CORE's installation/base path. func determine_basepath() -> bool: if FileAccess.file_exists("res://.corebasepath"): basepath = "res://" @@ -370,7 +361,6 @@ func determine_basepath() -> bool: return false return true -# Checks Godot's version ## Checks compatibility with the running version. func check_godot_version() -> bool: var version: Dictionary = Engine.get_version_info() @@ -400,6 +390,7 @@ func quit_safely(exitcode: int = 0) -> void: await cleanup() get_tree().quit(exitcode) +# Just ignore this. func _notification(what) -> void: match(what): NOTIFICATION_WM_CLOSE_REQUEST: diff --git a/src/erm.gd b/src/erm.gd index a242139..db0dcfd 100644 --- a/src/erm.gd +++ b/src/erm.gd @@ -18,14 +18,11 @@ ## Allows for awaited, batched and oneline requests. extends CoreBaseModule -## Contains a list of all queued downloads.[br] -## [b]Danger: [i]Don't modify this[/i][/b]. +# Contains a list of all queued downloads. var list_queue: Dictionary = {} -## Contains a list of all active downloads.[br] -## [b]Danger: [i]Don't modify this[/i][/b]. +# Contains a list of all active downloads. var list_active: Dictionary = {} -## Contains a liust of all completed downloads.[br] -## [b]Danger: [i]Don't modify this[/i][/b]. +# Contains a liust of all completed downloads. var list_complete: Dictionary = {} ## Determines how unsecure requests should be handled. @@ -107,7 +104,7 @@ func batch_awaited_request(urls: PackedStringArray, parse_utf8: bool, method: HT list_complete.erase(id) return dldata -## Internal function, do not call +# Does the work, but in a thread. 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) @@ -116,8 +113,7 @@ func _batch_awaited_request(url: String, parse_utf8: bool, method: HTTPClient.Me return id # +++ internal +++ -## Returns a new download id.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# Returns a new download id. func generate_id() -> int: var id = randi() if list_queue.has(id) or list_active.has(id): diff --git a/src/logger.gd b/src/logger.gd index 3097b21..5631d13 100644 --- a/src/logger.gd +++ b/src/logger.gd @@ -23,9 +23,7 @@ extends CoreBaseModule signal log_event -## Keeps track of all logger instances. -## Unused instances will be cleaned periodically. -## [b]Danger: [i]Don't modify this.[/i][/b] +# Keeps track of all logger instances. Unused instances will be cleaned periodically by CORE's scheduler. var instances: Array[CoreLoggerInstance] = [] ## Used to determine if running in verbose/command line mode.[br] @@ -70,8 +68,7 @@ func _pull_config() -> void: config_newlines_sizelimit = core.config.logger_newlines_sizelimit # +++ logging +++ -## The main logging function that does the heavy lifting.[br] -## [b]Danger: [i]Don't call this.[/i][/b] +# The main logging function that does the heavy lifting. func _log(level: CoreTypes.LoggerLevel, origin: String, message: String) -> void: if !is_level_allowed(level): emit_signal("log_event", false, level, origin, message, "") diff --git a/src/sms.gd b/src/sms.gd index c244855..56d06cf 100644 --- a/src/sms.gd +++ b/src/sms.gd @@ -22,24 +22,14 @@ 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] -## [b]Danger: [i]Don't modify this.[/i][/b] +# Scene collections var scenes_debug: Node = Node.new() -## The 'cutscene' scene collection.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_cutscene: Node = Node.new() -## The 'menu' scene collection.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_menu: Node = Node.new() -## The 'main' scene collection.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_main: Node = Node.new() -## The 'background' scene collection.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] var scenes_background: Node = Node.new() -## A list of all loaded scenes[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# A list of all loaded scenes. var scenes: Dictionary = {} # +++ module +++ diff --git a/src/storage.gd b/src/storage.gd index 391de50..9583b2b 100644 --- a/src/storage.gd +++ b/src/storage.gd @@ -23,15 +23,13 @@ extends CoreBaseModule ## 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.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# The parsed data inside the storage file. var storage: Dictionary = {} -## The location of the storage file.[br] -## [b]Danger: [i]Don't modify this.[/i][/b] +# The location of the storage file. var storage_location: String = "" # +++ file management +++ -## Opens a storage file into memory. +## Opens a storage file and loads it into memory. func open_storage(location: String, create_new: bool = true, sanity_check: bool = true, fail_on_sanity_check: bool = false) -> bool: if is_open: loggeri.error("Failed to open storage: A storage file is already open")