docs(gdscript): review and generate docs

Author: Goutte

docs/generators/gdscript.md

@@ -16,6 +16,7 @@
 
 import static org.openapitools.codegen.utils.StringUtils.camelize;
 
+
 public class GdscriptClientCodegen extends DefaultCodegen implements CodegenConfig {
 
     // All generated core classes will use this affixes both in class_name and file name.
@@ -190,7 +191,7 @@ public GdscriptClientCodegen() {
         );
 
         // It makes sense to package the generated code like a Godot addon, for ease of installation.
-        // Since most users will set the output dir, we perhaps ought to to document that fact.
+        // Since most users will set the output dir, we perhaps ought to document that fact.
         String addonName = "goas.client";
         outputFolder = "generated-code"
                 + File.separator + "gdscript"
@@ -245,10 +246,11 @@ public GdscriptClientCodegen() {
         cliOptions.add(new CliOption(ANTICOLLISION_SUFFIX, "Suffix added at the ending of reserved words")
                 .defaultValue(ANTICOLLISION_SUFFIX_VALUE));
 
-        // Also, I have not taken care of escaping things properly in the templates.
+        // Alas, I have not taken care of escaping things properly in the templates.
         // I'm not sure how to handle the different escaping strategies required.
-        LOGGER.warn("---- THE GENERATED CODE MAY BE UNSAFE AND MALICIOUS OAS FILES MAY HURT YOU ----");
-        LOGGER.warn("PLEASE READ *CAREFULLY* THE OAS FILE YOU ARE USING BEFORE YOU TRUST IT.");
+        // FIXME: we can't log like this here → too verbose
+        //LOGGER.warn("---- THE GENERATED CODE MAY BE UNSAFE AND MALICIOUS OAS FILES MAY HURT YOU ----");
+        //LOGGER.warn("PLEASE READ *CAREFULLY* THE OAS FILE YOU ARE USING BEFORE YOU TRUST IT.");
     }
 
     @Override
@@ -451,9 +453,9 @@ protected List<String> getReservedWords() {
                 "randfn", "randi", "randi_range", "randomize", "remap", "rid_allocate_id", "rid_from_int64",
                 "round", "roundf", "roundi", "seed", "sign", "signf", "signi", "sin", "sinh", "smoothstep",
                 "snapped", "sqrt", "step_decimals", "str", "str_to_var", "tan", "tanh", "typeof",
-                "var_to_bytes", "var_to_bytes_with_objects", "var_to_str", "weakref", "wrap", "wrapf",
+                "var_to_bytes", "var_to_bytes_with_objects", "var_to_str", "weakref", "wrap", "wrapf", "wrapi",
                 // Godot's global constants
-                "wrapi", "SIDE_LEFT", "SIDE_TOP", "SIDE_RIGHT", "SIDE_BOTTOM", "CORNER_TOP_LEFT",
+                "SIDE_LEFT", "SIDE_TOP", "SIDE_RIGHT", "SIDE_BOTTOM", "CORNER_TOP_LEFT",
                 "CORNER_TOP_RIGHT", "CORNER_BOTTOM_RIGHT", "CORNER_BOTTOM_LEFT", "VERTICAL", "HORIZONTAL",
                 "CLOCKWISE", "COUNTERCLOCKWISE", "HORIZONTAL_ALIGNMENT_LEFT", "HORIZONTAL_ALIGNMENT_CENTER",
                 "HORIZONTAL_ALIGNMENT_RIGHT", "HORIZONTAL_ALIGNMENT_FILL", "VERTICAL_ALIGNMENT_TOP",
@@ -585,8 +587,9 @@ protected List<String> getReservedWords() {
                 "OP_GREATER_EQUAL", "OP_ADD", "OP_SUBTRACT", "OP_MULTIPLY", "OP_DIVIDE", "OP_NEGATE",
                 "OP_POSITIVE", "OP_MODULE", "OP_POWER", "OP_SHIFT_LEFT", "OP_SHIFT_RIGHT", "OP_BIT_AND",
                 "OP_BIT_OR", "OP_BIT_XOR", "OP_BIT_NEGATE", "OP_AND", "OP_OR", "OP_XOR", "OP_NOT", "OP_IN",
+                "OP_MAX",
                 // Godot's singletons
-                "OP_MAX", "AudioServer", "CameraServer", "ClassDB", "DisplayServer", "Engine",
+                "AudioServer", "CameraServer", "ClassDB", "DisplayServer", "Engine",
                 "EngineDebugger", "Geometry2D", "Geometry3D", "GodotSharp", "IP", "Input", "InputMap",
                 "JavaClassWrapper", "JavaScriptBridge", "Marshalls", "NativeExtensionManager",
                 "NavigationMeshGenerator", "NavigationServer2D", "NavigationServer3D", "OS", "Performance",
@@ -606,9 +609,9 @@ protected List<String> getReservedWords() {
                 "var", "void", "yield",
                 // Constants
                 "PI", "TAU", "INF", "NaN",
-
+                // Primitive (lowercase) types
                 "float", "int", "bool",
-
+                // Types
                 "AABB",
                 "AcceptDialog",
                 "AESContext",

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/GdscriptClientCodegen.java

@@ -0,0 +1,29 @@
+package org.openapitools.codegen.gdscript;
+
+import org.openapitools.codegen.*;
+import org.openapitools.codegen.languages.GdscriptClientCodegen;
+import io.swagger.models.*;
+import io.swagger.models.properties.*;
+
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+@SuppressWarnings("static-method")
+public class GdscriptClientCodegenModelTest {
+
+    @Test(description = "convert a simple java model")
+    public void simpleModelTest() {
+        final Model model = new ModelImpl()
+                .description("a sample model")
+                .property("id", new LongProperty())
+                .property("name", new StringProperty())
+                .required("id")
+                .required("name");
+        final DefaultCodegen codegen = new GdscriptClientCodegen();
+
+        // TODO: Complete this test.
+        //Assert.fail("Not implemented.");
+    }
+
+}
+

modules/openapi-generator/src/test/java/org/openapitools/codegen/gdscript/GdscriptClientCodegenModelTest.java

@@ -0,0 +1,18 @@
+package org.openapitools.codegen.gdscript;
+
+import org.openapitools.codegen.languages.GdscriptClientCodegen;
+import org.testng.annotations.Test;
+
+import static org.mockito.Mockito.verify;
+
+public class GdscriptClientCodegenTest {
+
+    GdscriptClientCodegen clientCodegen = new GdscriptClientCodegen();
+
+    @Test
+    public void shouldSucceed() throws Exception {
+        // TODO: Complete this test.
+        //Assert.fail("Not implemented.");
+//        verify(clientCodegen).setArtifactVersion(GdscriptClientCodegenOptionsProvider.ARTIFACT_VERSION_VALUE);
+    }
+}

modules/openapi-generator/src/test/java/org/openapitools/codegen/gdscript/GdscriptClientCodegenTest.java

@@ -0,0 +1,37 @@
+package org.openapitools.codegen.gdscript;
+
+//import org.openapitools.codegen.AbstractOptionsTest;
+//import org.openapitools.codegen.CodegenConfig;
+//import org.openapitools.codegen.languages.GdscriptClientCodegen;
+//import org.openapitools.codegen.options.GdscriptClientOptionsProvider;
+//
+//import static org.mockito.Mockito.mock;
+//import static org.mockito.Mockito.verify;
+
+
+// NOTE:
+// This is commented out because it fails to use handlebars.
+// It is perhaps trivial to fix, but I could not figure it out.
+// Anyway, there's no test case in here right now, so it does not matter much.
+
+
+//public class GdscriptClientOptionsTest extends AbstractOptionsTest {
+//    private final GdscriptClientCodegen codegen = mock(GdscriptClientCodegen.class, mockSettings);
+//
+//    public GdscriptClientOptionsTest() {
+//        super(new GdscriptClientOptionsProvider());
+//    }
+//
+//    @Override
+//    protected CodegenConfig getCodegenConfig() {
+//        return codegen;
+//    }
+//
+//    @SuppressWarnings("unused")
+//    @Override
+//    protected void verifyOptions() {
+//        // TODO: Complete options using Mockito
+//        // verify(codegen).someMethod(arguments)
+//    }
+//}
+

modules/openapi-generator/src/test/java/org/openapitools/codegen/gdscript/GdscriptClientOptionsTest.java

@@ -7,7 +7,7 @@
 
 import java.util.Map;
 
-public class GdscriptClientCodegenOptionsProvider implements OptionsProvider {
+public class GdscriptClientOptionsProvider implements OptionsProvider {
 
 //    public static final String MODEL_PACKAGE_VALUE = "package";
 //    public static final String API_PACKAGE_VALUE = "apiPackage";
@@ -41,7 +41,7 @@ public Map<String, String> createOptions() {
                 .put(GdscriptClientCodegen.ANTICOLLISION_PREFIX, GdscriptClientCodegen.ANTICOLLISION_PREFIX_VALUE)
                 .put(GdscriptClientCodegen.ANTICOLLISION_SUFFIX, GdscriptClientCodegen.ANTICOLLISION_SUFFIX_VALUE)
 
-                // > "le remblai, c'était mieux avant"
+                // Things we *might* need (we'll see)
 
 //                .put(CodegenConstants.API_PACKAGE, API_PACKAGE_VALUE)
 //                .put(PhpClientCodegen.VARIABLE_NAMING_CONVENTION, VARIABLE_NAMING_CONVENTION_VALUE)
@@ -53,6 +53,7 @@ public Map<String, String> createOptions() {
 
                 // The following is required by CodeGen
 
+                //.put(CodegenConstants.TEMPLATING_ENGINE, "handlebars")
                 .put(CodegenConstants.SORT_PARAMS_BY_REQUIRED_FLAG, SORT_PARAMS_VALUE)
                 .put(CodegenConstants.SORT_MODEL_PROPERTIES_BY_REQUIRED_FLAG, SORT_MODEL_PROPERTIES_VALUE)
                 .put(CodegenConstants.ENSURE_UNIQUE_PARAMS, ENSURE_UNIQUE_PARAMS_VALUE)

…dscriptClientCodegenOptionsProvider.java …tions/GdscriptClientOptionsProvider.javamodules/openapi-generator/src/test/java/org/openapitools/codegen/options/GdscriptClientCodegenOptionsProvider.java renamed to modules/openapi-generator/src/test/java/org/openapitools/codegen/options/GdscriptClientOptionsProvider.java modules/openapi-generator/src/test/java/org/openapitools/codegen/options/GdscriptClientCodegenOptionsProvider.java renamed to modules/openapi-generator/src/test/java/org/openapitools/codegen/options/GdscriptClientOptionsProvider.java

@@ -1 +1 @@
-6.6.0-SNAPSHOT
+7.8.0-SNAPSHOT

samples/client/petstore/gdscript/addons/oas.petstore.client/.openapi-generator/VERSION

@@ -288,13 +288,13 @@ func _bzz_do_request_text(
 		on_failure.call(error)
 		return
 
+    # Keep polling for as long as the request is being processed.
 	while self._bzz_client.get_status() == HTTPClient.STATUS_REQUESTING:
-		# Keep polling for as long as the request is being processed.
-		self._bzz_client.poll()
 		self._bzz_config.log_debug("Requesting…")
 		if self._bzz_config.polling_interval_ms:
 			OS.delay_msec(self._bzz_config.polling_interval_ms)
 		await _bzz_next_loop_iteration()
+		self._bzz_client.poll()
 
 	if not self._bzz_client.has_response():
 		var error := DemoApiError.new()
@@ -321,14 +321,14 @@ func _bzz_do_request_text(
 	var response_bytes := PackedByteArray()
 
 	while self._bzz_client.get_status() == HTTPClient.STATUS_BODY:
-		self._bzz_client.poll()
 		var chunk = self._bzz_client.read_response_body_chunk()
 		if chunk.size() == 0:  # Got nothing, wait for buffers to fill a bit.
 			if self._bzz_config.polling_interval_ms:
 				OS.delay_usec(self._bzz_config.polling_interval_ms)
 			await _bzz_next_loop_iteration()
 		else:  # Yummy data has arrived
 			response_bytes = response_bytes + chunk
+		self._bzz_client.poll()
 
 	self._bzz_config.log_info("%s: RESPONSE %d (%d bytes)" % [
 		_bzz_name, response.code, response_bytes.size()

samples/client/petstore/gdscript/addons/oas.petstore.client/core/DemoApiBee.gd

@@ -42,14 +42,13 @@ enum LogLevel {
 }
 
 
-# Log level to configure verbosity.
-# @export_enum ain't working for ints yet (2023-03)
+## Log level to configure verbosity.
 @export var log_level := LogLevel.WARNING
 
 
-# The host to connect to, with or without the protocol scheme.
-# Eg: "gitea.com", "https://gitea.com"
-# We toggle TLS accordingly to the provided scheme, if any.
+## The host to connect to, with or without the protocol scheme.
+## Eg: "gitea.com", "https://gitea.com"
+## We toggle TLS accordingly to the provided scheme, if any.
 @export var host := BEE_DEFAULT_HOST:
 	set(value):
 		if value.begins_with("https://"):
@@ -61,14 +60,14 @@ enum LogLevel {
 		host = value
 
 
-# Port through which the connection will be established.
-# Note: changing the host may change the port as well if the scheme was provided, see above.
+## Port through which the connection will be established.
+## NOTE: changing the host may change the port as well if the scheme was provided, see above.
 @export var port := BEE_DEFAULT_PORT_HTTP
 
 
-# Headers used as base for all requests made by Api instances using this config.
-# Those are the lowest priority headers, and are merged with custom headers provided in the bee_request() method call
-# as well as the headers override below, to compute the final, actually sent headers.
+## Headers used as base for all requests made by Api instances using this config.
+## Those are the lowest priority headers, and are merged with custom headers provided in the bee_request() method call
+## as well as the headers override below, to compute the final, actually sent headers.
 @export var headers_base := {
 	# Stigmergy: everyone does what is left to do (like ants do)
 	"User-Agent": "Stigmergiac/1.0 (Godot)",
@@ -78,30 +77,30 @@ enum LogLevel {
 }
 
 
-# High-priority headers, they will always override other headers coming from the base above or the method call.
+## High-priority headers, they will always override other headers coming from the base above or the method call.
 @export var headers_override := {}
 
 
-# Duration of sleep between poll() calls.
+## Duration of sleep between poll() calls.
 @export var polling_interval_ms := BEE_DEFAULT_POLLING_INTERVAL_MS  # milliseconds
 
 
-# Enable the Transport Security Layer (packet encryption, HTTPS)
+## Enable the Transport Security Layer (packet encryption, HTTPS)
 @export var tls_enabled := false:
 	set(value):
 		tls_enabled = value
 		port = BEE_DEFAULT_PORT_HTTPS if tls_enabled else BEE_DEFAULT_PORT_HTTP
 
 
-# You should preload your *.crt file (the whole chain) in here if you want TLS.
-# I usually concatenate my /etc/ssl/certs/ca-certificates.crt and webserver certs here.
-# Remember to add the *.crt file to the exports, if necessary.
+## You should preload your *.crt file (the whole chain) in here if you want TLS.
+## I usually concatenate my /etc/ssl/certs/ca-certificates.crt and webserver certs here.
+## Remember to add the *.crt file to the exports, if necessary.
 @export var trusted_chain: X509Certificate  # only used if tls is enabled
 @export var common_name_override := ""  # for TLSOptions
 
 
-# Dynamic accessor using the TLS properties above, but you may inject your own
-# for example if you need to use TLSOptions.client_unsafe.  Best not @export this.
+## Dynamic accessor using the TLS properties above, but you may inject your own
+## for example if you need to use TLSOptions.client_unsafe.  Best not @export this.
 var tls_options: TLSOptions:
 	set(value):
 		tls_options = value
@@ -131,7 +130,7 @@ func log_debug(message: String):
 
 
 # Authentication method `petstore_auth`.
-# → Skipped: not implemented in the gdscript templates.  (contribs welcome)
+# → Skipped: not implemented in the gdscript templates.  (contribs are welcome)
 
 
 # Authentication method `api_key`.

samples/client/petstore/gdscript/addons/oas.petstore.client/core/DemoApiConfig.gd

@@ -14,22 +14,22 @@ class_name DemoApiError
 # it will trigger the error callback, with an instance of this as parameter.
 #
 
-# Helps finding the error in the code, among other things.
-# Could be a UUID, or even a translation key, so long as it's unique.
-# Right now we're mostly using a lowercase ~namespace joined by dots. (.)
+## Helps finding the error in the code, among other things.
+## Could be a UUID, or even a translation key, so long as it's unique.
+## Right now we're mostly using a lowercase ~namespace joined by dots. (.)
 @export var identifier := ""
 
-# A message for humans.  May be multiline.
+## A message for humans.  May be multiline.
 @export var message := ""
 
-# One of Godot's ERR_XXXX, when relevant.
+## One of Godot's ERR_XXXX, when relevant.
 @export var internal_code := OK
 
-# The HTTP response code, if any.  (usually >= 400)
-# DEPRECATED: prefer reading from response object below
+## The HTTP response code, if any.  (usually >= 400)
+## DEPRECATED: prefer reading from response object below
 @export var response_code := HTTPClient.RESPONSE_OK
 
-# The HTTP response, if any.
+## The HTTP response, if any.
 @export var response: DemoApiResponse