From 3b0a5bbfc5f1536577b074eb8db307f09f7940a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=80=20?=
 =?UTF-8?q?=D0=97=D0=B0=D1=86=D0=B5=D0=BF=D0=B8=D0=BD?= <az@mapswithme.com>
Date: Mon, 19 Feb 2018 13:43:27 +0300
Subject: [PATCH] [android] Added javadoc to Authorizer

---
 .../com/mapswithme/maps/auth/Authorizer.java  | 35 +++++++++++++------
 .../auth/BaseMwmAuthorizationFragment.java    | 19 +++++++++-
 .../data/BookmarkBackupController.java        |  2 +-
 3 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/android/src/com/mapswithme/maps/auth/Authorizer.java b/android/src/com/mapswithme/maps/auth/Authorizer.java
index e1a9c2913c..ede53c49a3 100644
--- a/android/src/com/mapswithme/maps/auth/Authorizer.java
+++ b/android/src/com/mapswithme/maps/auth/Authorizer.java
@@ -11,25 +11,38 @@ import android.text.TextUtils;
 import com.mapswithme.maps.Framework;
 import com.mapswithme.util.ConnectionState;
 
+/**
+ * An authorizer is responsible for an authorization for the Mapsme server,
+ * which is known as "Passport". This process is long and consists two big parts:<br>
+ *<br>
+ * 1. A user authentication via social networks which results in obtaining
+ * the <b>social auth token</b>.<br>
+ * 2. A user authorization for the Mapsme Server using the obtained social token on the first step.<br>
+ *<br>
+ *
+ * All callbacks of this authorizer may be listened through {@link Callback} interface. Also there is
+ * a method indicating whether the authorization (see step 2) in a progress
+ * or not - {@link #isAuthorizationInProgress()}.<br>
+ *<br>
+ *
+ * <b>IMPORTANT NOTE</b>: responsibility of memory leaking (context leaking) is completely
+ * on the client of this class. In common case, the careful attaching and detaching to/from instance
+ * of this class in activity's/fragment's lifecycle methods, such as onResume()/onPause
+ * or onStart()/onStop(), should be enough to avoid memory leaks.
+ */
 public class Authorizer implements AuthorizationListener
 {
   @NonNull
   private final Fragment mFragment;
   @Nullable
   private Callback mCallback;
-  private boolean mInProgress;
+  private boolean mIsAuthorizationInProgress;
 
   public Authorizer(@NonNull Fragment fragment)
-  {
-    this(fragment, null);
-  }
-
-  Authorizer(@NonNull Fragment fragment, @Nullable Callback callback)
   {
     mFragment = fragment;
   }
 
-
   public void attach(@NonNull Callback callback)
   {
     mCallback = callback;
@@ -68,7 +81,7 @@ public class Authorizer implements AuthorizationListener
     {
       @Framework.SocialTokenType
       int type = data.getIntExtra(Constants.EXTRA_TOKEN_TYPE, -1);
-      mInProgress = true;
+      mIsAuthorizationInProgress = true;
       if (mCallback != null)
         mCallback.onAuthorizationStart();
       Framework.nativeAuthenticateUser(socialToken, type, this);
@@ -78,14 +91,14 @@ public class Authorizer implements AuthorizationListener
   @Override
   public void onAuthorized(boolean success)
   {
-    mInProgress = false;
+    mIsAuthorizationInProgress = false;
     if (mCallback != null)
       mCallback.onAuthorizationFinish(success);
   }
 
-  public boolean isInProgress()
+  public boolean isAuthorizationInProgress()
   {
-    return mInProgress;
+    return mIsAuthorizationInProgress;
   }
 
   public boolean isAuthorized()
diff --git a/android/src/com/mapswithme/maps/auth/BaseMwmAuthorizationFragment.java b/android/src/com/mapswithme/maps/auth/BaseMwmAuthorizationFragment.java
index 43bbb3b883..1b07e30e71 100644
--- a/android/src/com/mapswithme/maps/auth/BaseMwmAuthorizationFragment.java
+++ b/android/src/com/mapswithme/maps/auth/BaseMwmAuthorizationFragment.java
@@ -1,6 +1,7 @@
 package com.mapswithme.maps.auth;
 
 import android.content.Intent;
+import android.support.annotation.CallSuper;
 import android.support.annotation.NonNull;
 
 import com.mapswithme.maps.base.BaseMwmToolbarFragment;
@@ -14,13 +15,29 @@ public abstract class BaseMwmAuthorizationFragment extends BaseMwmToolbarFragmen
     implements Authorizer.Callback
 {
   @NonNull
-  private final Authorizer mAuthorizer = new Authorizer(this, this);
+  private final Authorizer mAuthorizer = new Authorizer(this);
 
   protected void authorize()
   {
     mAuthorizer.authorize();
   }
 
+  @Override
+  @CallSuper
+  public void onStart()
+  {
+    super.onStart();
+    mAuthorizer.attach(this);
+  }
+
+  @Override
+  @CallSuper
+  public void onStop()
+  {
+    super.onStop();
+    mAuthorizer.detach();
+  }
+
   @Override
   public void onActivityResult(int requestCode, int resultCode, Intent data)
   {
diff --git a/android/src/com/mapswithme/maps/bookmarks/data/BookmarkBackupController.java b/android/src/com/mapswithme/maps/bookmarks/data/BookmarkBackupController.java
index 5a65c7ff12..a356250235 100644
--- a/android/src/com/mapswithme/maps/bookmarks/data/BookmarkBackupController.java
+++ b/android/src/com/mapswithme/maps/bookmarks/data/BookmarkBackupController.java
@@ -49,7 +49,7 @@ public class BookmarkBackupController implements Authorizer.Callback
     {
       mBackupView.setMessage(context.getString(R.string.bookmarks_message_unauthorized_user));
       mBackupView.setButtonLabel(context.getString(R.string.authorization_button_sign_in));
-      if (mAuthorizer.isInProgress())
+      if (mAuthorizer.isAuthorizationInProgress())
       {
         mBackupView.showProgressBar();
         mBackupView.hideButton();