doc: improve connections doc

Author: dorotaphanSiili

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/AbstractApiGearConnection.h

@@ -8,8 +8,10 @@
 #include "AbstractApiGearConnection.generated.h"
 
 /**
- * @brief Abstract base for IApiGearConnection implementation
- * Implements state management and handles common reconnection functionality. Exposes delegates.
+ * Abstract base for IApiGearConnection implementation.
+ * Handles common reconnection functionality.
+ * Keeps the connection state updated.
+ * Exposes delegates for getting notifications of the connection state.
  * Does not add the actual connection handling - it needs to be implemented by the final connection.
  */
 UCLASS(Abstract, NotBlueprintable)
@@ -19,6 +21,7 @@ class APIGEAR_API UAbstractApiGearConnection : public UObject, public IApiGearCo
 
 public:
 	explicit UAbstractApiGearConnection(const FObjectInitializer& ObjectInitializer);
+
 	FApiGearConnectionIsConnectedDelegate& GetIsConnectedChangedDelegate() override;
 	FApiGearConnectionStateChangedDelegate& GetConnectionStateChangedDelegate() override;
 
@@ -29,6 +32,8 @@ class APIGEAR_API UAbstractApiGearConnection : public UObject, public IApiGearCo
 	void OnDisconnected(bool bReconnect) final;
 	void Connect() final;
 	void Disconnect() final;
+
+	/* Use this function to block AutoReconnect behavior temporarily until the connection is disconnected. */
 	void StopReconnecting() override;
 	bool IsConnected() PURE_VIRTUAL(UAbstractApiGearConnection::IsConnected, return false;);
 
@@ -43,19 +48,39 @@ class APIGEAR_API UAbstractApiGearConnection : public UObject, public IApiGearCo
 private:
 	void SetConnectionState(EApiGearConnectionState State);
 
+	/** 
+	 * Implement in derived class to provide actual logic specific for your connection for when network connection is established.
+	 * Should not be used directly, instead use OnConnected().
+	 */
 	virtual void OnConnected_Implementation() PURE_VIRTUAL(UAbstractApiGearConnection::OnConnected_Implementation, );
+	/**
+	 * Implement in derived class to provide actual logic specific for your connection for when the network connection is over
+	 * Should not be used directly, instead use OnDisonnected().
+	 */
 	virtual void OnDisconnected_Implementation(bool bReconnect) PURE_VIRTUAL(UAbstractApiGearConnection::OnDisconnected_Implementation, );
+	/**
+	 * Implement in derived class to provide actual logic specific for your connection to establish a connection
+	 * Should not be used directly, instead use Connect().
+	 */
 	virtual void Connect_Implementation() PURE_VIRTUAL(UAbstractApiGearConnection::Connect_Implementation, );
+	/** 
+	 * Implement in derived class to provide actual logic specific for your connection to close connection
+	 * Should not be used directly, instead use Disconnect().
+	 */
 	virtual void Disconnect_Implementation() PURE_VIRTUAL(UAbstractApiGearConnection::Disconnect_Implementation, );
 
 	FApiGearConnectionIsConnectedDelegate IsConnectedChanged;
 	FApiGearConnectionStateChangedDelegate ConnectionStateChanged;
 
+	/** If set to true, the connection if not running will try to reconnect with a time interval, until succeeded */
 	bool bIsAutoReconnectEnabled;
+	/** Used when the bIsAutoReconnectEnabled is on but reconnection functionality needs to be temporarily stop for disconnecting. */
 	bool bStopReconnectingRequested;
 
+	/** Reconnection timer*/
 	ApiGear::FDelegateHandle RetryTickerHandle;
 
+	/** Reconnection timer delegate*/
 	FTickerDelegate RetryTickerDelegate;
 
 	EApiGearConnectionState ConnectionState;

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/ApiGearConnection.h

@@ -18,12 +18,12 @@ enum class EApiGearConnectionState : uint8
 	Connected UMETA(Displayname = "Connected")
 };
 
-///  Used when Network Layer Connection changes its state to connected(true) or any other connection state (false).
+/**  Used when Network Layer Connection changes its state to connected(true) or any other connection state(false). */
 DECLARE_MULTICAST_DELEGATE_OneParam(FApiGearConnectionIsConnectedDelegate, bool);
-///  Used when Network Layer Connection changes its state.
+/** Used when Network Layer Connection changes its state. */
 DECLARE_MULTICAST_DELEGATE_OneParam(FApiGearConnectionStateChangedDelegate, EApiGearConnectionState);
 /**
- * @brief Used when the interface client changes its subscription status:
+ * Used when the interface client changes its subscription status:
  * either is plugged in the network and ready to use with protocol of your choice (true)
  * or it won't be able to properly communicate with server side (false).
  * An established network connection (ConnectionIsConnectedDelegate with true parameter) is often necessary, but not sufficient (depending on your setup and used protocol)
@@ -32,11 +32,12 @@ DECLARE_MULTICAST_DELEGATE_OneParam(FApiGearConnectionStateChangedDelegate, EApi
 DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FApiGearRemoteApiSubscriptionStatusChangedDelegate, bool, IsSubscribed);
 
 /** 
- * @brief An interface for all connections meant to be used by ApiGear
+ * An interface for all connections meant to be used by ApiGear
  * ensures all connections have:
  * - settings for reconnection
  * - current state
  * - general state and settings accessors
+ * @see AbstractApiGearConnection for implementation of common functionality.
  */
 UINTERFACE(MinimalAPI, meta = (CannotImplementInterfaceInBlueprint))
 class UApiGearConnection : public UInterface
@@ -49,34 +50,51 @@ class APIGEAR_API IApiGearConnection
 	GENERATED_BODY()
 
 public:
+
+	/** Returns a delegate for notifications informing whether connection is ready to use
+	* @see ApiGearConnectionIsConnectedDelegate
+	*/
 	virtual FApiGearConnectionIsConnectedDelegate& GetIsConnectedChangedDelegate() = 0;
+	/** Returns a delegate for notifications informing about the connection state.
+	* @see FApiGearConnectionStateChangedDelegate
+	*/
 	virtual FApiGearConnectionStateChangedDelegate& GetConnectionStateChangedDelegate() = 0;
 
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual void Configure(FString InServerURL, bool bInAutoReconnectEnabled) = 0;
 
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
+	/** Call this function to request connection to be established */
 	virtual void Connect() = 0;
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
+	/** A callback for when the network connection is established,
+	 * Use to finalize connect related actions in the implemented connection, 
+	 * For notifications on when connection is disconnected use GetIsConnectedChangedDelegate or ApiGearConnectionStateChangedDelegate.
+	 */
 	virtual void OnConnected() = 0;
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
+	/** Call this function to request closing connection. */
 	virtual void Disconnect() = 0;
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
+	/** A callback for when the network connection has closed,
+	 * use to finalize disconnect-related actions in the implemented connection.
+	 * For notifications on when connection is disconnected use GetIsConnectedChangedDelegate or ApiGearConnectionStateChangedDelegate.
+	 */
 	virtual void OnDisconnected(bool bReconnect) = 0;
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual bool IsConnected() = 0;
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual void StopReconnecting() = 0;
 
-	/** Returns the endpoint identifier for this connection, e.g. simulation or phone_service */
+	/** Returns the endpoint identifier for this connection, e.g. simulation or phone_service*/
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual FString GetUniqueEndpointIdentifier() const = 0;
 
 	/** Returns the server URL */
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual FString GetServerURL() const = 0;
 
-	/** Returns the type identifier for this connection, e.g. olink */
+	/** Returns the identifier of protocol used for this connection, e.g. olink */
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|Connection")
 	virtual FString GetConnectionProtocolIdentifier() const = 0;
 

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/ApiGearConnectionsStore.h

@@ -13,12 +13,13 @@
 APIGEAR_API DECLARE_LOG_CATEGORY_EXTERN(LogApiGearConnectionsStore, Log, All);
 
 /**
- * Implements the connections store for the ApiGear plugin.
+ * Creates and stores connections based on configured connections in settings.
+ *  @see ApiGearSettings
  * 
- * Can handle all connections which inherit from the IApiGearConnection interface.
- * To register your own protocol, you need to call RegisterConnectionFactory
- * before this class/module is initialized. The ApiGearOLink module is an example
- * how this can be done.
+ * Handles all connections which inherit from the IApiGearConnection interface.
+ * @warning For custom protocols make sure you've registered your own protocol factory with a RegisterConnectionFactory.
+ * before this class/module is initialized.
+ * You may use implemented ApiGearOLink module as an example.
  */
 UCLASS(BlueprintType)
 class APIGEAR_API UApiGearConnectionsStore : public UEngineSubsystem
@@ -30,7 +31,11 @@ class APIGEAR_API UApiGearConnectionsStore : public UEngineSubsystem
 	/** A type of function for creating connections*/
 	using FConnectionFactoryFunction = TFunction<TScriptInterface<IApiGearConnection>(UObject*, FString)>;
 
-	/** register factories for different types of connections */
+	/** 
+	 * Register custom factories of connections.
+	 * This function must be called before this class or module are initialized.
+	 * @see ApiGearOLink.
+	 */
 	static bool RegisterConnectionFactory(FString ConnectionTypeIdentifier, FConnectionFactoryFunction FactoryFunction);
 
 	// USubssystem functions
@@ -62,6 +67,7 @@ class APIGEAR_API UApiGearConnectionsStore : public UEngineSubsystem
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|ConnectionsStore")
 	TArray<FString> GetAvailableProtocols() const;
 
+	/** Replaces ApiGear plugin settings configured for the project with all currently added connections. */
 	UFUNCTION(BlueprintCallable, Category = "ApiGear|ConnectionsStore")
 	void OverwriteAndSaveConnectionsToSettings() const;
 

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/ApiGearSettings.h

@@ -7,7 +7,7 @@
 #include "Engine/EngineTypes.h"
 #include "ApiGearSettings.generated.h"
 
-/** Settings per connection for ApiGear plugins */
+/** Settings for a connection in ApiGear plugins */
 USTRUCT()
 struct FApiGearConnectionSetting
 {
@@ -19,23 +19,36 @@ struct FApiGearConnectionSetting
 	 */
 	FString ProtocolIdentifier{"olink"};
 
-	/** Choose the server to connect to */
+	/** 
+	 * Choose the server to connect to
+	 * this is a full address with a port
+	 * It will be used "as is", so if you need any pre or post fixes like
+	 * "ws://" make sure the field contains it.
+	 */
 	UPROPERTY(EditAnywhere, config, Category = ApiGearConnectionSetting)
 	FString URL{TEXT("ws://127.0.0.1:8000/ws")};
 
-	/** Choose whether to automatically reconnect */
+	/** Enable reconnect functionality for connection, also automatically starts the connection for the first time */
 	UPROPERTY(EditAnywhere, config, Category = ApiGearConnectionSetting)
 	bool AutoReconnectEnabled{false};
 };
 
 /**
- * Implements the settings for the ApiGear plugin.
+ * Stores settings for each connection and other network related settings for ApiGear plugin.
+ * For each connection settings a connections is created by ApiGearConnectionsStore on startup,
+ * For other custom protocols make sure that a factory for it is added to ApiGearConnectionsStore.
+ * @see ApiGearConnectionsStore
  */
 UCLASS(Config = Engine, DefaultConfig)
 class APIGEAR_API UApiGearSettings : public UObject
 {
 	GENERATED_UCLASS_BODY()
-	/** Choose the server to connect to */
+	/** 
+	 * Url of tracer server to connect to.
+	 * This is a full address with a port
+	 * It will be used "as is", so if you need any pre or post fixes like
+	 * "ws://" make sure the field contains it.
+	 */
 	UPROPERTY(EditAnywhere, config, Category = TracerSetup, meta = (ConfigRestartRequired = true))
 	FString Tracer_URL;
 
@@ -47,15 +60,20 @@ class APIGEAR_API UApiGearSettings : public UObject
 	UPROPERTY(EditAnywhere, config, Category = TracerSetup, meta = (ConfigRestartRequired = true))
 	bool Tracer_EnableDebugLog;
 
-	/** Save and overwrite runtime modifications to the connections on exit */
+	/**
+	 * Save and overwrite runtime modifications to the connections on exit.
+	 * The property is checked on exit.
+	 * If set to false, all the changes (compared with the startup) will be lost, even if it was set to true during application lifetime.
+	 * You still can save current settings state during editing regardless of this property with a ApiGearConnectionsStore::OverwriteAndSaveConnectionsToSettings function.
+	 */
 	UPROPERTY(EditAnywhere, config, Category = ConnectionSetup, meta = (ConfigRestartRequired = true, Display = "Use runtime changes instead of settings"))
 	bool bSaveRuntimeEdit;
 
-	// Automatically start
+	/** Automatically starts the Hosted OLink Server. */
 	UPROPERTY(EditAnywhere, config, Category = OLinkHostSetup)
 	bool OLINK_AutoStart;
 
-	// On which Port to listen
+	/** Port on which Hosted OLink Server is listening.*/
 	UPROPERTY(EditAnywhere, config, Category = OLinkHostSetup)
 	uint32 OLINK_Port;
 

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/ApiGearTicker.h

@@ -4,6 +4,8 @@
 #include "Runtime/Launch/Resources/Version.h"
 #include "Containers/Ticker.h"
 
+
+/** This is a a helper file to provide version independent ticker functionality */
 namespace ApiGear
 {
 #if (ENGINE_MAJOR_VERSION >= 5)

goldenmaster/Plugins/ApiGear/Source/ApiGear/Public/apigear.json.adapter.h

@@ -8,16 +8,40 @@
 #define JSON_NOEXCEPTION 1
 #include <nlohmann/json.hpp>
 
+/**
+ * Converts json formated data into FString.
+ * The functions signature must follow the nlohmann from_jason function rules.
+ * It is automatically called in usage j.get<FString>();
+ * @param j an input json formated data
+ * @param p FString that will be filled with data from j.
+ *  In case data is malformed or not convertible to FString the function will throw.
+ */
 static void from_json(const nlohmann::json& j, FString& p)
 {
 	p = FString(UTF8_TO_TCHAR(j.get<std::string>().c_str()));
 }
 
+/**
+ * Converts FString into json formated data.
+ * The functions signature must follow the nlohmann to_json function rules.
+ * It is automatically called in usage j = p;
+ * @param j a json type data that will be filled with data from p
+ * @param p an input from which json data will be filled.
+ */
 static void to_json(nlohmann::json& j, const FString& value)
 {
 	j = TCHAR_TO_UTF8(*value);
 }
 
+/**
+ * Converts json formated data into TArray of T type elements.
+ * The T type needs to be either std type or have its from_json function.
+ * The functions signature must follow the nlohmann from_jason function rules.
+ * It is automatically called in usage j.get<TArray<T>>();
+ * @param j an input json formated data
+ * @param p FString that will be filled with data from j.
+ *  In case data is malformed or not convertible to FString the function will throw.
+ */
 template <typename T>
 void from_json(const nlohmann::json& j, TArray<T>& p)
 {
@@ -29,6 +53,14 @@ void from_json(const nlohmann::json& j, TArray<T>& p)
 	}
 }
 
+/**
+ * Converts TArray of T type elements into json formated data.
+ * The T type needs to be either std type or have its to_json function.
+ * The functions signature must follow the nlohmann to_json function rules.
+ * It is automatically called in usage j = p;
+ * @param j a json type data that will be filled with data from p
+ * @param p an input from which json data will be filled.
+ */
 template <typename T>
 void to_json(nlohmann::json& j, const TArray<T>& p)
 {