From 2dc028490573df68f17df53226ef77d793054edb Mon Sep 17 00:00:00 2001 From: Kari Vatjus-Anttila Date: Sun, 5 Dec 2021 21:31:17 +0200 Subject: [PATCH] Add missing Javadoc statements --- .../de/golfgl/gdxgamesvcs/GameJoltClient.java | 45 ++++++++++++---- .../gdxgamesvcs/IGameServiceClient.java | 13 ++--- .../src/de/golfgl/gdxgamesvcs/GpgsClient.java | 54 ++++++++++--------- .../src/de/golfgl/gdxgamesvcs/GpgsClient.java | 12 ++--- .../src/de/golfgl/gdxgamesvcs/KongClient.java | 7 ++- 5 files changed, 82 insertions(+), 49 deletions(-) diff --git a/core-gamejolt/src/de/golfgl/gdxgamesvcs/GameJoltClient.java b/core-gamejolt/src/de/golfgl/gdxgamesvcs/GameJoltClient.java index 43843c8..f0f0acf 100644 --- a/core-gamejolt/src/de/golfgl/gdxgamesvcs/GameJoltClient.java +++ b/core-gamejolt/src/de/golfgl/gdxgamesvcs/GameJoltClient.java @@ -77,7 +77,7 @@ public GameJoltClient initialize(String gjAppId, String gjAppPrivateKey) { /** * sets up the mapper for score table calls * - * @param scoreTableMapper + * @param scoreTableMapper Id mapper * @return this for method chaining */ public GameJoltClient setGjScoreTableMapper(IGameServiceIdMapper scoreTableMapper) { @@ -88,7 +88,7 @@ public GameJoltClient setGjScoreTableMapper(IGameServiceIdMapper scoreT /** * sets up the mapper for trophy calls * - * @param trophyMapper + * @param trophyMapper Id mapper * @return this for method chaining */ public GameJoltClient setGjTrophyMapper(IGameServiceIdMapper trophyMapper) { @@ -104,8 +104,8 @@ public String getUserToken() { /** * Sets the GameJolt user token. Not possible when connected! * - * @param userToken - * @return + * @param userToken The user token + * @return this for method chaining */ public GameJoltClient setUserToken(String userToken) { if (isSessionActive()) @@ -118,8 +118,8 @@ public GameJoltClient setUserToken(String userToken) { /** * Sets the GameJolt user name. Not possible when connected! * - * @param userName - * @return + * @param userName The username + * @return this for method chaining */ public GameJoltClient setUserName(String userName) { if (isSessionActive()) @@ -132,7 +132,7 @@ public GameJoltClient setUserName(String userName) { /** * see {@link #setGuestName(String)} * - * @return + * @return String that represents a guest name */ public String getGuestName() { return guestName; @@ -141,7 +141,9 @@ public String getGuestName() { /** * GameJolt can post scores to scoreboards without an authenticated user. Set a guest name to enable this featuee. * - * @param guestName + * @param guestName String that represents a guest name + * + * @return this for method chaining */ public GameJoltClient setGuestName(String guestName) { this.guestName = guestName; @@ -545,6 +547,11 @@ public boolean fetchLeaderboardEntries(String leaderBoardId, int limit, boolean /** * converts GameJolt's scoreboard return json to our own data type. This method is for overriding purposes + * + * @param rank rank of the player + * @param score score value + * + * @return A leaderboard entry */ protected ILeaderBoardEntry scoreJsonToObject(int rank, JsonValue score) { return GjScoreboardEntry.fromJson(score, rank, getPlayerDisplayName()); @@ -553,7 +560,7 @@ protected ILeaderBoardEntry scoreJsonToObject(int rank, JsonValue score) { /** * see {@link #getEventKeyPrefix()} * - * @return + * @return event key prefix */ public String getEventKeyPrefix() { return eventKeyPrefix; @@ -573,6 +580,7 @@ public String getEventKeyPrefix() { * * @param eventKeyPrefix Your prefix for event keys, or null to deactivate using global data storage for events. * Default is null. + * @return Instance of GameJoltClient for method chaining. */ public GameJoltClient setEventKeyPrefix(String eventKeyPrefix) { this.eventKeyPrefix = eventKeyPrefix; @@ -611,8 +619,8 @@ public boolean submitEvent(String eventId, int increment) { /** * Use careful! It resets your event to 0. Needed for first time initialization. * - * @param eventId - */ + * @param eventId event to reset + **/ public void initializeOrResetEventKey(String eventId) { if (!initialized) { Gdx.app.error(GAMESERVICE_ID, "Cannot submit event: set app ID via initialize() first"); @@ -715,6 +723,10 @@ public void cancelled() { /** * Helper method when just interested if GameJolt request was successful + * + * @param json String to parse + * + * @return boolean that represents whether or not the response was a success */ protected boolean parseSuccessFromResponse(String json) { JsonValue response = null; @@ -849,6 +861,12 @@ public boolean isFeatureSupported(GameServiceFeature feature) { /** * content must be without special chars ampersand or question mark - use Base64 when not sure! + * + * @param dataKey data key used in the operation + * @param globalKey global key used in the operation + * @param content content of the request + * + * @return a HTTP request object */ protected Net.HttpRequest buildStoreDataRequest(String dataKey, boolean globalKey, String content) { Map params = new HashMap(); @@ -914,6 +932,11 @@ public void cancelled() { /** * Load data is done with dump format + * + * @param dataKey Data key of the request + * @param globalKey Global key boolean + * + * @return A HTTP request object */ protected Net.HttpRequest buildLoadDataRequest(String dataKey, boolean globalKey) { Map params = new HashMap(); diff --git a/core/src/de/golfgl/gdxgamesvcs/IGameServiceClient.java b/core/src/de/golfgl/gdxgamesvcs/IGameServiceClient.java index 7d7861f..e845c02 100644 --- a/core/src/de/golfgl/gdxgamesvcs/IGameServiceClient.java +++ b/core/src/de/golfgl/gdxgamesvcs/IGameServiceClient.java @@ -123,7 +123,7 @@ public interface IGameServiceClient { /** * Checks if a user session connection attempt is running * - * @return + * @return boolean which describes if the connection attempt is pending */ boolean isConnectionPending(); @@ -148,7 +148,7 @@ public interface IGameServiceClient { * Should only be called when {@link GameServiceFeature#FetchAchievements} is supported, * check {@link #isFeatureSupported(GameServiceFeature)} prior to call this method. * - * @param callback + * @param callback the listener that will be notified about the result * @return false if fetch attempt could not be made. Response listener will not get called in that case. * @throws UnsupportedOperationException if not supported by game service client, so check * {@link #isFeatureSupported(GameServiceFeature)} prior to call this method. @@ -162,8 +162,8 @@ public interface IGameServiceClient { * info level. If the connection is not open, this is no error - some game services allow submitting scores * without a user session. * - * @param leaderboardId - * @param score + * @param leaderboardId leaderboard id where the score is submitted + * @param score score that will be submitted * @param tag an optional information to post on the leader board, if API supports it. May be null. * @return false if submission couldn't be made. true if submit request was made (regardless if it was successful) */ @@ -267,6 +267,7 @@ boolean fetchLeaderboardEntries(String leaderBoardId, int limit, boolean related * {@link GameServiceFeature#GameStateStorage} ()} before calling. * * @param fileId file id to load from when multiple files are supported. Ignored otherwise + * @param responseListener the listener that will be notified about the result */ void loadGameState(String fileId, ILoadGameStateResponseListener responseListener); @@ -284,7 +285,7 @@ boolean fetchLeaderboardEntries(String leaderBoardId, int limit, boolean related /** * Fetch current player's game states. * - * @param callback + * @param callback the listener that will be notified about the result * @return false if fetch attempt could not be made. Response listener will not get called in that case. * @throws UnsupportedOperationException if not supported by game service client, so check * {@link #isFeatureSupported(GameServiceFeature)} prior to call this method. @@ -294,7 +295,7 @@ boolean fetchLeaderboardEntries(String leaderBoardId, int limit, boolean related /** * Queries if a certain feature is available for this Game Service * - * @param feature + * @param feature feature to query if it is supported * @return true if feature is supported by implementation and game service */ boolean isFeatureSupported(GameServiceFeature feature); diff --git a/desktop-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java b/desktop-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java index 074f15d..bbb4f97 100644 --- a/desktop-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java +++ b/desktop-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java @@ -213,8 +213,10 @@ public GpgsClient initialize(String applicationName, InputStream clientSecret, b * Initialize with a clientSecretFile. * see {@link #initialize(String, InputStream, boolean)} * - * @param applicationName - * @param clientSecretFile + * @param applicationName name of the application + * @param clientSecretFile client secret file containing the secrets needed to connect + * @param enableDriveAPI whether or not to enable drive API + * * @return method chaining */ public GpgsClient initialize(String applicationName, FileHandle clientSecretFile, boolean enableDriveAPI) { @@ -225,7 +227,7 @@ public GpgsClient initialize(String applicationName, FileHandle clientSecretFile /** * sets up the mapper for leader board ids * - * @param gpgsLeaderboardIdMapper + * @param gpgsLeaderboardIdMapper id mapper * @return this for method chaining */ public GpgsClient setGpgsLeaderboardIdMapper(IGameServiceIdMapper gpgsLeaderboardIdMapper) { @@ -236,7 +238,7 @@ public GpgsClient setGpgsLeaderboardIdMapper(IGameServiceIdMapper gpgsLe /** * sets up the mapper for leader achievement ids * - * @param gpgsAchievementIdMapper + * @param gpgsAchievementIdMapper id mapper * @return this for method chaining */ public GpgsClient setGpgsAchievementIdMapper(IGameServiceIdMapper gpgsAchievementIdMapper) { @@ -246,7 +248,9 @@ public GpgsClient setGpgsAchievementIdMapper(IGameServiceIdMapper gpgsAc /** * Try to authorize user. This method is blocking until user accept - * autorization. + * authorization. + * + * @param silent boolean to determine whether to do the sign in silently */ private void waitForUserAuthorization(boolean silent) { // load user token or open browser for user authorizations. @@ -374,10 +378,10 @@ public void run() throws IOException { /** * Blocking version of {@link #submitToLeaderboard(String, long, String)} * - * @param leaderboardId - * @param score - * @param tag - * @throws IOException + * @param leaderboardId the leaderboard id to submit the score to + * @param score score value to submit + * @param tag optional tag thats attached to the score entry + * @throws IOException on error cases throws an IOException */ public void submitToLeaderboardSync(String leaderboardId, long score, String tag) throws IOException { if (gpgsLeaderboardIdMapper != null) @@ -403,8 +407,8 @@ public void run() throws IOException { /** * Blocking version of {@link #submitEvent(String, int)} * - * @param eventId - * @param increment + * @param eventId event Id + * @param increment increment value to use */ public void submitEventSync(String eventId, int increment) { // TODO don't know the API for this use case @@ -427,8 +431,8 @@ public void run() throws IOException { /** * Blocking version of {@link #unlockAchievement(String)} * - * @param achievementId - * @throws IOException + * @param achievementId achievment Id to unlock + * @throws IOException on error cases throws an IOException */ public void unlockAchievementSync(String achievementId) throws IOException { if (gpgsAchievementIdMapper != null) @@ -455,10 +459,10 @@ public void run() throws IOException { /** * Blocking version of {@link #incrementAchievement(String, int, float)} * - * @param achievementId - * @param incNum - * @param completionPercentage - * @throws IOException + * @param achievementId achievment id to increment + * @param incNum increment amount + * @param completionPercentage completion percentage + * @throws IOException on error cases throws an IOException */ public void incrementAchievementSync(String achievementId, int incNum, float completionPercentage) throws IOException { @@ -494,7 +498,7 @@ public void run() throws IOException { * Blocking version of {@link #fetchGameStatesSync()} * * @return game states - * @throws IOException + * @throws IOException on error cases throws an IOException */ public Array fetchGameStatesSync() throws IOException { @@ -598,10 +602,10 @@ private File findFileByNameSync(String name) throws IOException { /** * Blocking version of {@link #saveGameState(String, byte[], long, ISaveGameStateResponseListener)} * - * @param fileId - * @param gameState - * @param progressValue - * @throws IOException + * @param fileId file Id for the save + * @param gameState byte array containing the save state + * @param progressValue progress value of the game state + * @throws IOException on error cases throws an IOException */ public void saveGameStateSync(String fileId, byte[] gameState, long progressValue) throws IOException { @@ -668,9 +672,9 @@ public void run() throws IOException { /** * Blocking version of {@link #loadGameState(String, ILoadGameStateResponseListener)} * - * @param fileId + * @param fileId file id of the game state * @return game state data - * @throws IOException + * @throws IOException on error cases throws an IOException */ public byte[] loadGameStateSync(String fileId) throws IOException { @@ -712,7 +716,7 @@ public void run() throws IOException { * Blocking version of {@link #fetchAchievements(IFetchAchievementsResponseListener)} * * @return the achievement list - * @throws IOException + * @throws IOException on error cases throws an IOException */ public Array fetchAchievementsSync() throws IOException { diff --git a/html-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java b/html-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java index 9901fec..03770ad 100644 --- a/html-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java +++ b/html-gpgs/src/de/golfgl/gdxgamesvcs/GpgsClient.java @@ -52,7 +52,7 @@ public class GpgsClient implements IGameServiceClient { /** * sets up the mapper for leader board ids * - * @param gpgsLeaderboardIdMapper + * @param gpgsLeaderboardIdMapper mapper that maps a given constant to a leaderboard id * @return this for method chaining */ public GpgsClient setGpgsLeaderboardIdMapper(IGameServiceIdMapper gpgsLeaderboardIdMapper) { @@ -63,7 +63,7 @@ public GpgsClient setGpgsLeaderboardIdMapper(IGameServiceIdMapper gpgsLe /** * sets up the mapper for leader achievement ids * - * @param gpgsAchievementIdMapper + * @param gpgsAchievementIdMapper mapper that maps a given constant to a achievment id * @return this for method chaining */ public GpgsClient setGpgsAchievementIdMapper(IGameServiceIdMapper gpgsAchievementIdMapper) { @@ -577,8 +577,8 @@ protected native void findDriveFileId(String fileId, IDoWithDriveFileId doWithDr /** * gets the real download url and calls downloadFileFromDrive, or the response listener - * @param driveFileId - * @param responseListener + * @param driveFileId the drive file id + * @param responseListener the listener that will be notified about the result */ protected native void loadFileFromDrive(String driveFileId, final ILoadGameStateResponseListener responseListener) /*-{ var that=this; @@ -620,8 +620,8 @@ public void cancelled() { /** * this can be used instead of loadFileFromDrive/downloadFileFromDrive... but it does not work on Firefox * Firefox does not follow a redirect that is given back to the real download url - * @param driveFileId - * @param responseListener + * @param driveFileId the drive file id + * @param responseListener the listener that will be notified about the result */ protected void loadFileFromDriveV3(String driveFileId, final ILoadGameStateResponseListener responseListener) { Net.HttpRequest httpRequest = new Net.HttpRequest(Net.HttpMethods.GET); diff --git a/html-kong/src/de/golfgl/gdxgamesvcs/KongClient.java b/html-kong/src/de/golfgl/gdxgamesvcs/KongClient.java index fe7e642..7a34c15 100644 --- a/html-kong/src/de/golfgl/gdxgamesvcs/KongClient.java +++ b/html-kong/src/de/golfgl/gdxgamesvcs/KongClient.java @@ -255,7 +255,12 @@ public boolean fetchLeaderboardEntries(String leaderBoardId, final int limit, bo } /** - * override this method for tunneling through own server or other needs + * Override this method for tunneling through own server or other needs + * + * @param statId the stat id + * @param playerRelated is the requested results related to the player + * + * @return the resulting HTTP request */ protected Net.HttpRequest buildQueryStatRequest(Integer statId, boolean playerRelated) { String url = "https://api.kongregate.com/api/high_scores/" +