Added comments to 19 functions across 4 files

.komment/komment.json

@@ -1,17 +1,22 @@
 {
   "meta": {
     "version": "1",
-    "updated_at": "2024-08-12T19:47:47.827Z",
+    "updated_at": "2024-08-12T20:40:47.143Z",
     "created_at": "2024-08-12T18:03:18.789Z",
     "pipelines": [
       "5290e9fb-b07e-4f3a-b1dc-ade204499fa5",
-      "6ce8c123-10dc-4848-87ac-c2fd538e4116"
+      "6ce8c123-10dc-4848-87ac-c2fd538e4116",
+      "e3c5077a-79f2-4dd1-9c80-093fc7876e9c"
     ]
   },
   "lookup": [
     [
       "client/src/main/java/io/sensable/client/adapter/ExpandableListAdapter.java",
-      "client/src/main/java/io/sensable/client/component/FontFitTextView.java"
+      "client/src/main/java/io/sensable/client/component/FontFitTextView.java",
+      "client/src/main/java/io/sensable/client/adapter/TabsPagerAdapter.java",
+      "client/src/main/java/io/sensable/client/SensorHelper.java",
+      "client/src/main/java/io/sensable/client/SensableUser.java",
+      "client/src/main/java/io/sensable/client/SensorListActivity.java"
     ]
   ]
 }

client/src/main/java/io/sensable/client/SensableUser.java

@@ -19,10 +19,10 @@
  * Created by simonmadine on 12/07/2014.
  */
 /**
- * is responsible for handling user authentication and settings retrieval in an Android
+ * Is responsible for handling user authentication and settings retrieval in an Android
  * application. It provides functions to login, logout, retrieve user settings, and
- * save the user's information to preferences. Additionally, it offers methods to
- * delete the saved user information and update the login status.
+ * save user information to preferences. The class interacts with a backend API using
+ * Retrofit to authenticate users and update their status.
  */
 public class SensableUser {
 
@@ -57,10 +57,11 @@ public SensableUser(SharedPreferences sharedPreferences, Context context) {
     }
 
     /**
-     * retrieves user information from shared preferences and sets it to a `User` object,
-     * returning `true` if successful or `false` otherwise.
-     * 
-     * @returns a boolean value indicating whether the user is logged in or not.
+     * Retrieves user preferences from shared preferences, such as username, email, and
+     * access token. If any of these values are present, it updates a user object with
+     * these values and sets a flag indicating whether an access token is available.
+     *
+     * @returns a boolean value indicating user login status.
      */
     private boolean readUserFromPreferences() {
         String username = sharedPreferences.getString(context.getString(R.string.saved_username), "");
@@ -85,78 +86,40 @@ private boolean readUserFromPreferences() {
     }
 
     /**
-     * takes a `UserLogin` object and a `CallbackInterface` object as inputs, calls the
-     * service's login method to authenticate the user, and updates the user's data and
-     * saves it to preferences upon success.
-     * 
-     * @param userLogin UserLogin object containing the login credentials of the user to
-     * be authenticated.
-     * 
-     * 	- `userLogin`: This is an instance of the `UserLogin` class, which contains
-     * information about the user attempting to log in.
-     * 	+ `username`: The username of the user attempting to log in.
-     * 	+ `email`: The email address of the user attempting to log in.
-     * 
-     * The function call is made to the `service` object's `login` method, passing in
-     * `userLogin` and a callback interface `cb`. The callback interface has two methods:
-     * `success` and `failure`.
-     * 
-     * In the `success` method, if the login attempt is successful, the `User` object's
-     * properties are set to the deserialized response data, including the `username` and
-     * `email`. Additionally, the `loggedIn` flag is set to `true`, and the `accessToken`
-     * property is set to the `accessToken` property of the `User` object. Finally, the
-     * `saveUserToPreferences()` method is called to save the user's data to preferences.
-     * 
-     * In the `failure` method, an error message is logged to the console if the login
-     * attempt fails.
-     * 
-     * @param cb `CallbackInterface` that will receive updates on the login status.
-     * 
-     * The `CallbackInterface cb` is an interface with two methods: `loginStatusUpdate(loggedIn)`
-     * and `failure(RetrofitError retrofitError)`. The `loginStatusUpdate` method is
-     * invoked when the login callback is successful, and it takes a boolean parameter
-     * `loggedIn` indicating whether the user is logged in or not. The `failure` method
-     * is invoked when there is an error during the login process, and it takes a
-     * `RetrofitError` object as its parameter.
+     * Performs a login request using the authentication service, and upon success, it
+     * sets user details, updates preferences, and notifies the callback interface about
+     * the login status update. Upon failure, it logs an error message to the console.
+     *
+     * @param userLogin credentials to be used for login authentication and is passed to
+     * the `service.login()` method.
+     *
+     * @param cb CallbackInterface object that notifies the login status update to the
+     * caller of the login method.
+     *
+     * CallbackInterface cb: It has a loginStatusUpdate method, which is called with a
+     * boolean parameter.
      */
     public void login(UserLogin userLogin, final MainActivity.CallbackInterface cb) {
 
         service.login(userLogin, new Callback<User>() {
             /**
-             * handles a successful login callback from the authentication service. It sets the
-             * user's username, email, and access token (if available), updates the user's
-             * preferences, and notifies the login status update to the callback interface.
-             * 
-             * @param user login result, containing the user's username and email address.
-             * 
-             * 	- `username`: The username of the user.
-             * 	- `email`: The email address of the user.
-             * 	- `accessToken`: An access token for the user.
-             * 
-             * The `mUser` object is set to the deserialized `user` object, and various attributes
-             * of `mUser` are updated. Additionally, a call to `saveUserToPreferences()` is made
-             * to persist the user's data to preferences. Finally, the login status is updated
-             * using `cb.loginStatusUpdate(loggedIn)`.
-             * 
-             * @param response response from the login API, which provides the user's authentication
-             * information.
-             * 
-             * 	- `user`: A `User` object representing the authenticated user.
-             * 	- `accessToken`: The access token obtained from the authentication process, which
-             * can be used for further requests.
-             * 
-             * The function performs the following actions:
-             * 
-             * 1/ Logs a message to the debug log with the username of the successfully authenticated
-             * user.
-             * 2/ Sets the `username` and `email` properties of the `mUser` object to those of
-             * the `user` object.
-             * 3/ Sets the `loggedIn` property of the `mUser` object to `true`.
-             * 4/ Checks if an access token was obtained and, if so, sets the `accessToken`
-             * property of the `mUser` object to the obtained value.
-             * 5/ Calls the `saveUserToPreferences()` function to save the `mUser` object to user
-             * preferences.
-             * 6/ Updates the login status in the caller with the newly set `loggedIn` property.
+             * Updates a local user object with received data, sets login status to true if an
+             * access token is available, and calls a callback method to update login status. If
+             * no access token is present, it triggers another method for user settings.
+             *
+             * @param user user's data, whose details such as username and email are retrieved
+             * to update the local user model.
+             *
+             * Extracted:
+             * - `getUsername()`: Returns a string representing the username.
+             * - `getEmail()`: Returns a string representing the email.
+             * - `getAccessToken()`: Returns a possibly null token.
+             *
+             * @param response response from the server to the login request, but it is not used
+             * within the function as its value is ignored.
+             *
+             * The `response` object contains no relevant data or methods within its scope, serving
+             * only as a generic callback parameter.
              */
             @Override
             public void success(User user, Response response) {
@@ -182,14 +145,11 @@ public void success(User user, Response response) {
             }
 
             /**
-             * is called when a login request fails, and it logs an error message to the console
-             * using the `Log.e()` method.
-             * 
-             * @param retrofitError error that occurred during the login callback, which is then
-             * logged with a message indicating the nature of the error.
-             * 
-             * 	- `toString()`: Returns a string representation of the error object, which can
-             * be used for logging or display to the user.
+             * Handles failures when attempting to perform a login operation using Retrofit. It
+             * logs an error message with the error details to the Android log using the specified
+             * tag, indicating that the login callback has failed.
+             *
+             * @param retrofitError error that occurred during the API call.
              */
             @Override
             public void failure(RetrofitError retrofitError) {
@@ -199,33 +159,33 @@ public void failure(RetrofitError retrofitError) {
     }
 
     /**
-     * sets user's settings by calling API with given username and returns access token
-     * if successful.
+     * Retrieves user settings from a login API, updates the local user object with
+     * received information, and saves it to preferences if an access token is provided.
+     * It handles successful responses by updating the user details and saving them, and
+     * failed responses by logging errors.
      */
     public void userSettings() {
 
         service.settings(mUser.getUsername(), new Callback<User>() {
             /**
-             * handles the callback response from the login API, updates the user object with the
-             * received information, and saves it to preferences if an access token is provided.
-             * 
-             * @param user authenticated user returned by the authentication service, providing
-             * the user's username and email address, as well as an access token if available.
-             * 
-             * 	- `username`: The username of the user.
-             * 	- `email`: The email address of the user.
-             * 	- `accessToken`: The access token of the user.
-             * 
-             * @param response result of the login API call, providing the user's authentication
-             * status and other relevant information.
-             * 
-             * 	- `user`: A `User` object representing the user who has successfully logged in.
-             * 	- `accessToken`: The access token obtained through the login process, which can
-             * be used for further authenticated API requests.
-             * 
-             * The function then updates the `mUser` field with the values of `user`, sets
-             * `loggedIn` to `true`, and saves the user details to the preferences file if
-             * `hasAccessToken` is set to `true`.
+             * Handles a successful login operation by updating local user data, setting login
+             * status to true, and saving the access token if provided. It logs relevant information,
+             * such as user credentials and access token, for debugging purposes.
+             *
+             * @param user authenticated user, whose properties such as username, email, and
+             * access token are updated and logged accordingly.
+             *
+             * * Username
+             * * Email
+             * * AccessToken
+             *
+             * @param response response from the authentication service, which is not used within
+             * the method.
+             *
+             * The response has no explicit properties mentioned, implying that it may be an
+             * object or a class with default constructors. However, based on its presence in the
+             * method signature, it likely contains information about the success status and
+             * possibly other details related to user authentication.
              */
             @Override
             public void success(User user, Response response) {
@@ -247,17 +207,12 @@ public void success(User user, Response response) {
             }
 
             /**
-             * is called when a Retrofit error occurs during the login callback. It logs an error
-             * message to the console using the `Log.e()` method, including the error details in
-             * the message.
-             * 
-             * @param retrofitError error object generated by the Retrofit API call, which contains
-             * information about the failure of the login callback.
-             * 
-             * 	- `retrofitError.message`: String value representing the error message in
-             * human-readable form.
-             * 	- `retrofitError.statusCode`: Integer value representing the HTTP status code
-             * associated with the error, if applicable.
+             * Logs an error message with a given tag and Retrofit error when a login operation
+             * fails. The error message includes the `toString()` representation of the Retrofit
+             * error object.
+             *
+             * @param retrofitError exception thrown when a Retrofit request fails, providing
+             * details about the error.
              */
             @Override
             public void failure(RetrofitError retrofitError) {
@@ -267,8 +222,10 @@ public void failure(RetrofitError retrofitError) {
     }
 
     /**
-     * saves user information to shared preferences, including username, email, and access
-     * token.
+     * Logs the user's information and stores it in the device's preferences using
+     * SharedPreferences.Editor. It saves the username, email, and access token to
+     * designated keys in the preferences file. The changes are committed immediately
+     * after saving.
      */
     private void saveUserToPreferences() {
         Log.d(TAG, "Saving: " + mUser.getUsername() + ", " + mUser.getEmail() + ", " + mUser.getAccessToken());
@@ -280,15 +237,15 @@ private void saveUserToPreferences() {
     }
 
     /**
-     * removes saved user information from SharedPreferences and updates login status,
-     * access token, and user data to empty values.
-     * 
-     * @param cb CallbackInterface, which is an interface that provides a method for
-     * updating the login status of the user after the save operation is completed.
-     * 
-     * 	- `CallbackInterface cb`: This is an interface that provides methods for updating
-     * the login status of the user. It has one method, `loginStatusUpdate`, which takes
-     * a boolean parameter indicating whether the user is logged in or not.
+     * Removes previously saved user credentials from SharedPreferences, resets the
+     * `mUser`, `loggedIn`, and `hasAccessToken` variables, and updates the login status
+     * through a callback interface.
+     *
+     * @param cb CallbackInterface, which is used to notify the caller of the login status
+     * update after deleting saved user data.
+     *
+     * Interface: CallbackInterface
+     * Type: final MainActivity.CallbackInterface
      */
     public void deleteSavedUser(final MainActivity.CallbackInterface cb) {
         SharedPreferences.Editor editor = sharedPreferences.edit();