Merge pull request #92 from mlabs-haskell/rmgaray/add-missing-docs-middleware

Add missing docs to paima-middleware

Author: rmgaray

addons/@mlabs-haskell/cip-30-callbacks/cip_30_callbacks.gd

@@ -2,10 +2,33 @@ extends Node
 class_name Cip30Callbacks
 ## Provides a CIP-30 wrapper for a wallet in a web environment.
 ## 
-## Used to register a CIP-30 wallet in a browser environment by adding
+## Used to register a godot-cardano wallet in a browser environment by adding
 ## GDScript callbacks to the global [code]window.cardano.godot[/code] Object. These callbacks
 ## defer their implementation to a [Cip30WalletApi] object, which is required for
-## initializing the class ([method Cip30Callbacks._init]).
+## initializing the class ([method Cip30Callbacks._init]).[br][br]
+##
+## A standard use of this class involves first creating a [Cip30WalletApi] object, which
+## implements most methods necessary for a CIP-30 wallet. In practice, you will want
+## to extend [Cip30WalletApi] and implement its virtual methods by deferring to an
+## existing godot-cardano wallet (like [OnlineWallet]).[br][br]
+##
+## With an instantiated [Cip30WalletApi], it is possible to wrap it in a [Cip30Callbacks].
+## The method [method Cip30Callbacks.add_to] can then be used for registering the wallet in the
+## browser window:[br][br]
+##
+## Example:[br][br]
+##
+## The window object is retrieved using the JavaScriptBridge interface[br]
+## [code]var window = JavaScriptBridge.get_interface("window")[/code][br][br]
+##
+## Then a class extending [Cip30WalletApi] is instantiated...[br]
+## [code]var cip_30_wallet = ...[/code][br][br]
+##
+## ... and registered in the window[br]
+## [code]Cip30Callbacks.new(cip_30_wallet).add_to(window)[/code][br][br]
+##
+## The result of this is that any web application can now use a godot-cardano provided wallet
+## via the CIP-30 interface available in the browser window.
 
 # NOTE
 # [JsCip30Api] contains a JS script that creates the `window.cardano.godot` Object
@@ -74,8 +97,8 @@ func _cb_sign_data(args):
 	var signing_address: String = args[2]
 	var data_hex: String = args[3]
 
-	# TODO: If we want proper CIP-30 support, we should parse the address (could be hex or bech32)
-	# to pub key and differentiate between ProofGeneration and AddressNotPK errors
+	# Possible improvement: Parse the address (could be hex or bech32) to pub key and
+	# differentiate between ProofGeneration and AddressNotPK errors
 
 	# Paima framework will pass bech32 encoded Address into the sing request if the wallet is not Nami
 	if !_cip_30_wallet.owns_address(signing_address):

addons/@mlabs-haskell/cip-30-callbacks/cip_30_js_api.gd

@@ -6,8 +6,6 @@ class_name JsCip30Api
 ## This class is used internally by [Cip30Callbacks]. If you want to use the wallet
 ## provided by godot-cardano in a web environment, check the documentation for that
 ## class instead.[br][br]
-##
-## You should only use this class if you know what you are doing.
 
 ## Initialize `window.cardano` (if it does not exist yet) and register the
 ## godot-cardano wallet.

addons/@mlabs-haskell/cip-30-callbacks/cip_30_wallet_api.gd

@@ -4,8 +4,9 @@ class_name Cip30WalletApi
 ## Virtual class for implementing a CIP-30 compatible wallet
 ##
 ## This class represents a CIP-30 compatible wallet. Inherit it and override
-## all of its methods to obtain a CIP-30 wallet that may be used to initialize
-## a [Cip30Callbacks] object (check [method Cip30Callbacks._init]).
+## all of its methods to obtain a CIP-30 wallet that may be registered in the browser
+## window with [Cip30Callbacks]. Check that class to see an example
+## of use.
 
 ## [b]WARNING: Virtual function.[/b][br]
 ## Return the address of the wallet as a [String].

addons/@mlabs-haskell/paima-middleware/paima_middleware.gd

@@ -1,12 +1,54 @@
 extends RefCounted
 class_name PaimaMiddleware
 
-## Wrapper for core of Paima middleware.
+## Wrapper for the core of Paima middleware.
 ## 
-## Provides API for logging-in and querying `RoundExecutor`.
-## All calls wrap JS object with Paima middleware. Handling of JS Promises is done
-## via signals and `await`s.
-
+## Provides an API for logging-in and querying the `RoundExecutor`.[br][br]
+##
+## This API deals mostly with objects from the Paima middleware, and hence uses
+## [JavaScriptObject]s for many different things. Most importantly, the API is
+## initialized with the [code]paima_endpoints[/code] object.[br][br]
+##
+## Most methods exposed in this API are asynchronous. As such, they can be [code]await[/code]ed
+## or a callback can be bound to their respective signals.[br][br]
+## 
+## [b]How to obtain [code]paima_endpoints[/code][/b][br][br]
+##
+## This object is provided by the Paima middleware ([code]paimaMiddleware.js[/code]), and in Javascript
+## it can be easily brought into scope with an import statement:[br][br]
+##
+## [code]import endpoints from './paima/paimaMiddleware.js'[/code][br][br]
+##
+## Unfortunately, in GDScript it is not as easy. Import statements are not available,
+## so only global objects may be accessed, such as [code]window[/code].[br][br]
+##
+## Hence, the main way of obtaining [code]paima_endpoints[/code] is by attaching it
+## to the global [code]window[/code] object when the web page is loaded. In order
+## to do this, the web export template for the project must be modified accordingly:[br][br]
+##
+## [code][preset.0.options][/code][br]
+## [code]...[/code][br]
+## [code]html/head_include="<script type=\"module\">[/code][br]
+## [code]import endpoints from './paima/paimaMiddleware.js';[/code][br]
+## [code]window.paima_endpoints = endpoints;[/code][br][br]
+##
+## In GDScript, the [code]window[/code] (and thus [code]paima_endpoints[/code])
+## can be easily retrieved (check [method _init] docs).[br][br]
+##
+## [b]How to use the class[/b][br][br]
+##
+## The core methods available in [code]paima_endpoints[/code] are game-independent
+## and may be used directly from [PaimaMiddleware] without calling directly into
+## Javascript code (e.g: [method login], [method queryRoundExecutor]).[br][br]
+##
+## However, for method that are specific to a given game, the [code]paima_endpoints[/code]
+## object must be used directly and calls into Javascript are necessary. To retrieve
+## the endpoints object, use [method get_endpoints]. Consult this method's documentation
+## to learn how to call into Javascript from GDScript.
+
+## Wallet mode
+##
+## The kind of wallet to be used when logging into Paima.
 enum WalletMode  { 
 	EVM_INJECTED = 0, 
 	EVM_ETHERS = 1,
@@ -16,53 +58,82 @@ enum WalletMode  {
 	ALGORAND =5
 	}
 
+## Login information
+##
+## Used in [method PaimaMiddleware.login]
 class LoginInfo:
 	var _wallet_name: String
-	var _mode: int
+	var _mode: WalletMode
 	var _prefer_batcher: bool
 
-	## For Cardano wallets `prefer_batcher` should be set to `true` 
-	## as they can work only through Paima barcher
+	## Create [PaimaMiddleware.LoginInfo] by providing a [param wallet_name], a [param mode] and a
+	## [param prefer_batcher_flag].[br][br]
+	## For Cardano wallets, [param prefer_batcher] should always be set
+	## to [code]true[/code], as they can only work through the Paima batcher.
 	func _init(
 		wallet_name: String, 
-		mode: int, 
+		mode: WalletMode, 
 		prefer_batcher: bool
 	) -> void:
 		_wallet_name = wallet_name
-		_mode = 	mode
+		_mode = mode
 		_prefer_batcher = prefer_batcher
 
 var _endpoints: JavaScriptObject
 var _paima_wallet: JavaScriptObject
 
-var console = JavaScriptBridge.get_interface("console")
+## The browser console, provided here for convenience
+var console := JavaScriptBridge.get_interface("console")
 
+## A [PaimaMiddleware] is initialized by providing an [param endpoints]
+## object, which is normally made available under the [code]window[/code] object[br][br]
+## [code]var endpoints = JavaScriptBridge.get_interface("window").paima_endpoints[/code][br]
+## [code]var middleware = PaimaMiddleware(endpoints)
 func _init(endpoints: JavaScriptObject) -> void:
 	_endpoints = endpoints
 	assert(_endpoints)
 
+## Get the middleware endpoints, which can be used for executing middleware functions.[br]
+## The core functions are already wrapped by [PaimaMiddleware] in a more convenient form,
+## use this function for wrapping endpoints [b]not[/b] provided by the class (i.e: endpoints specific to
+## your game).[br][br]
+##
+## For example, if you want to execute a [code]join_match[/code] function:[br][br]
+##
+## First, you define a GDScript callback you want to run after joining the match[br]
+## [code]function join_match_cb(join_result: JavaScriptObject) -> void:[/code][br]
+## [code]    ...[/code][br][br]
+##
+## Then, you wrap the GDScript callback in a Javascript callback using [method JavasScriptBridge.create_callback][br]
+## [code]var join_match_cb_js := JavaScriptBridge.create_callback(join_match_cb)[/code][br][br]
+##
+## Finally, you get the the endpoints object and execute [code]join_match[/code]. The return value
+## will be a promise to which you can attach your Javascript callback using the Promise API.[br]
+## [code]middleware.get_endpoints().join_match(...).then()[/code]
 func get_endpoints() -> JavaScriptObject:
 	return _endpoints
-	
+
+## Get the wallet being used by the Paima middleware
 func get_wallet() -> JavaScriptObject:
 	return _paima_wallet
 
+## Get the wallet address 
+# TODO: Provide a return type for this function?
 func get_wallet_address():
 	return _paima_wallet.result.walletAddress
 
-## Login
-### The func
-func login(login_info: LoginInfo, on_login_cb = null) -> bool:
+## Log into Paima using [param login_info].
+func login(login_info: LoginInfo) -> bool:
 	var js_login_info = _to_js_login_info(login_info)
 	console.log("GD:Paima: login_info: ", js_login_info)
 	_endpoints.userWalletLogin(js_login_info).then(_on_login_js)
 	var login_successful = await on_paima_login
 	return login_successful
 
-### Signal for `await`
+## Emitted by [method login]
 signal on_paima_login(success: bool)
 
-### Callback
+# Callback
 var _on_login_js = JavaScriptBridge.create_callback(_on_login)
 func _on_login(args) -> void:
 	var wallet = args[0]
@@ -75,6 +146,8 @@ func _on_login(args) -> void:
 		console.log("Paima wallet login result:", wallet)
 		on_paima_login.emit(false)
 
+## Returns [code]true[/code] if a wallet was successfully set for the Paima
+## middleware.
 func wallet_is_set() -> bool:
 	return  _paima_wallet && _paima_wallet.success
 
@@ -87,8 +160,8 @@ func _to_js_login_info(login_info: LoginInfo) -> JavaScriptObject:
 	info.preference = pref
 	return info
 
-## Query round executor
-### The func
+## Query the state of the round executor by providing a [parama lobby_id] and
+## a [param round_number].
 func query_round_executor(lobby_id: String, round_number: int) -> RoundExecutor:
 	_endpoints.getRoundExecutor(lobby_id, round_number).then(_on_executor_query_response_js)
 	var re = await on_executor_response
@@ -100,12 +173,12 @@ func query_round_executor(lobby_id: String, round_number: int) -> RoundExecutor:
 		executor = null
 	return executor
 
-### JS callback
-var _on_executor_query_response_js = JavaScriptBridge.create_callback(on_executor_query_response)
-func on_executor_query_response(args) -> void:
+# JS callback
+var _on_executor_query_response_js = JavaScriptBridge.create_callback(_on_executor_query_response)
+func _on_executor_query_response(args) -> void:
 	on_executor_response.emit(args[0])
 
-### Signal for `await`
+## Emitted by [method query_round_executor]
 signal on_executor_response(re_result: JavaScriptObject)
 
 func _new_js_obj() -> JavaScriptObject:

paima-demo/godot-cip-30-frontend/game_middleware.gd

@@ -6,7 +6,7 @@ extends RefCounted
 ## Internal state is then used in the `_process(...)` of the parent node to adjust UI.
 class_name GameMiddleware
 
-var console = JavaScriptBridge.get_interface("console")
+var console: JavaScriptObject = JavaScriptBridge.get_interface("console")
 var _player_stats: JavaScriptObject
 var _middleware: PaimaMiddleware
 var _endpoints: JavaScriptObject
@@ -47,7 +47,7 @@ func update_player_stats():
 	else:
 		print("GD:Paima: wallet login was not successful, check wallet by `show wallet` button")
 
-### Callback
+# Callback
 var _on_stats_received_js = JavaScriptBridge.create_callback(_on_stats_received)
 func _on_stats_received(args):
 	_player_stats = args[0]

paima-demo/godot-cip-30-frontend/main.gd

@@ -9,8 +9,6 @@ var buttons_grid
 var ui_grid
 var walet_picker: HBoxContainer 
 
-
-
 # Called when the node enters the scene tree for the first time.
 func _ready():
 	print("GD: starting cardano-godot Paima demo")