Fix commons-app#1828: Add missing Javadocs and tidy up code in nearby package (commons-app#2133)

* Add Javadocs
* Remove unused variables, methods, fragments, imports, classes

Author: neslihanturan

app/src/main/java/fr/free/nrw/commons/di/FragmentBuilderModule.java

@@ -16,7 +16,6 @@
 import fr.free.nrw.commons.nearby.NearbyFragment;
 import fr.free.nrw.commons.nearby.NearbyListFragment;
 import fr.free.nrw.commons.nearby.NearbyMapFragment;
-import fr.free.nrw.commons.nearby.NoPermissionsFragment;
 import fr.free.nrw.commons.settings.SettingsFragment;
 
 @Module
@@ -38,9 +37,6 @@ public abstract class FragmentBuilderModule {
     @ContributesAndroidInjector
     abstract NearbyMapFragment bindNearbyMapFragment();
 
-    @ContributesAndroidInjector
-    abstract NoPermissionsFragment bindNoPermissionsFragment();
-
     @ContributesAndroidInjector
     abstract SettingsFragment bindSettingsFragment();
 

app/src/main/java/fr/free/nrw/commons/nearby/NearbyController.java

@@ -5,7 +5,6 @@
 import android.content.res.Resources;
 import android.graphics.Bitmap;
 import android.support.graphics.drawable.VectorDrawableCompat;
-import android.util.Log;
 
 import com.mapbox.mapboxsdk.annotations.IconFactory;
 
@@ -179,6 +178,9 @@ public static List<NearbyBaseMarker> loadAttractionsFromLocationToBaseMarkerOpti
         return baseMarkerOptions;
     }
 
+    /**
+     * We pass this variable as a group of placeList and boundaryCoordinates
+     */
     public class NearbyPlacesInfo {
         public List<Place> placeList; // List of nearby places
         public LatLng[] boundaryCoordinates; // Corners of nearby area

app/src/main/java/fr/free/nrw/commons/nearby/NearbyFragment.java

@@ -14,7 +14,6 @@
 import android.support.design.widget.Snackbar;
 import android.support.v4.app.FragmentTransaction;
 import android.support.v7.app.AlertDialog;
-import android.util.Log;
 import android.view.LayoutInflater;
 import android.view.View;
 import android.view.ViewGroup;
@@ -211,6 +210,10 @@ public void onSlide(View bottomSheet, float slideOffset) {
         bottomSheetBehaviorForDetails.setState(BottomSheetBehavior.STATE_HIDDEN);
     }
 
+    /**
+     * Sets camera position, zoom level according to sheet positions
+     * @param bottomSheetState expanded, collapsed or hidden
+     */
     public void prepareViewsForSheetPosition(int bottomSheetState) {
         // TODO
     }
@@ -243,7 +246,7 @@ public void onWikidataEditSuccessful() {
     /**
      * This method should be the single point to load/refresh nearby places
      *
-     * @param locationChangeType defines if location shanged significantly or slightly
+     * @param locationChangeType defines if location changed significantly or slightly
      */
     public void refreshView(LocationServiceManager.LocationChangeType locationChangeType) {
         Timber.d("Refreshing nearby places");
@@ -359,7 +362,6 @@ public void refreshViewForCustomLocation(LatLng customLatLng, boolean refreshFor
      * @param nearbyPlacesInfo This variable has place list information and distances.
      */
     private void populatePlacesFromCustomLocation(NearbyController.NearbyPlacesInfo nearbyPlacesInfo) {
-        //NearbyMapFragment nearbyMapFragment = getMapFragment();
         if (nearbyMapFragment != null) {
             nearbyMapFragment.searchThisAreaButtonProgressBar.setVisibility(View.GONE);
         }
@@ -374,6 +376,11 @@ private void populatePlacesFromCustomLocation(NearbyController.NearbyPlacesInfo
         }
     }
 
+    /**
+     * Turns nearby place lists and boundary coordinates into gson and update map and list fragments
+     * accordingly
+     * @param nearbyPlacesInfo a variable holds both nearby place list and boundary coordinates
+     */
     private void populatePlaces(NearbyController.NearbyPlacesInfo nearbyPlacesInfo) {
         Timber.d("Populating nearby places");
         List<Place> placeList = nearbyPlacesInfo.placeList;
@@ -390,7 +397,6 @@ private void populatePlaces(NearbyController.NearbyPlacesInfo nearbyPlacesInfo)
         }
 
         bundle.putString("PlaceList", gsonPlaceList);
-        //bundle.putString("CurLatLng", gsonCurLatLng);
         bundle.putString("BoundaryCoord", gsonBoundaryCoordinates);
 
         // First time to init fragments
@@ -412,7 +418,7 @@ private void populatePlaces(NearbyController.NearbyPlacesInfo nearbyPlacesInfo)
     /**
      * Lock nearby view updates while updating map or list. Because we don't want new update calls
      * when we already updating for old location update.
-     * @param lock
+     * @param lock true if we should lock nearby map
      */
     private void lockNearbyView(boolean lock) {
         if (lock) {
@@ -426,6 +432,18 @@ private void lockNearbyView(boolean lock) {
         }
     }
 
+    /**
+     * Updates map fragment,
+     * For slight update: camera follows users location
+     * For significant update: nearby markers are removed and new markers added again
+     * Slight updates stop if user is checking another area of map
+     *
+     * @param updateViaButton search this area button is clicked
+     * @param isSlightUpdate Means no need to update markers, just follow user location with camera
+     * @param customLatLng Will be used for updates for other locations than users current location.
+     *                     Ie. when we use search this area feature
+     * @param nearbyPlacesInfo Includes nearby places list and boundary coordinates
+     */
     private void updateMapFragment(boolean updateViaButton, boolean isSlightUpdate, @Nullable LatLng customLatLng, @Nullable NearbyController.NearbyPlacesInfo nearbyPlacesInfo) {
 
         if (nearbyMapFragment.searchThisAreaModeOn) {
@@ -499,6 +517,10 @@ private void updateMapFragment(boolean updateViaButton, boolean isSlightUpdate,
         }
     }
 
+    /**
+     * Updates already existing list fragment with bundle includes nearby places and boundary
+     * coordinates
+     */
     private void updateListFragment() {
         nearbyListFragment.setBundleForUpdates(bundle);
         nearbyListFragment.updateNearbyListSignificantly();
@@ -537,6 +559,9 @@ private void setListFragment() {
         fragmentTransaction.commitAllowingStateLoss();
     }
 
+    /**
+     * Hides progress bar
+     */
     private void hideProgressBar() {
         if (progressBar != null) {
             progressBar.setVisibility(View.GONE);
@@ -576,12 +601,18 @@ private void registerLocationUpdates() {
         }
     }
 
+    /**
+     * Requests location permission if activity is not null
+     */
     private void requestLocationPermissions() {
         if (!getActivity().isFinishing()) {
             locationManager.requestPermissions(getActivity());
         }
     }
 
+    /**
+     * Will warn user if location is denied
+     */
     private void showLocationPermissionDeniedErrorDialog() {
         new AlertDialog.Builder(getActivity())
                 .setMessage(R.string.nearby_needs_permissions)
@@ -671,6 +702,9 @@ private void showErrorMessage(String message) {
         ViewUtil.showLongToast(getActivity(), message);
     }
 
+    /**
+     * Adds network broadcast receiver to recognize connection established
+     */
     private void addNetworkBroadcastReceiver() {
         if (!FragmentUtils.isFragmentUIActive(this)) {
             return;
@@ -708,6 +742,10 @@ public void onResume() {
         resumeFragment();
         }
 
+    /**
+     * Perform nearby operations on nearby tab selected
+     * @param onOrientationChanged pass orientation changed info to fragment
+     */
     public void onTabSelected(boolean onOrientationChanged) {
         Timber.d("On nearby tab selected");
         this.onOrientationChanged = onOrientationChanged;

app/src/main/java/fr/free/nrw/commons/nearby/NearbyListFragment.java

@@ -92,6 +92,9 @@ public void onViewCreated(View view, Bundle savedInstanceState) {
         recyclerView.setAdapter(adapterFactory.create(getPlaceListFromBundle(bundle)));
     }
 
+    /**
+     * Updates nearby list elements all together
+     */
     public void updateNearbyListSignificantly() {
         try {
             adapterFactory.updateAdapterData(getPlaceListFromBundle(bundleForUpdates), (RVRendererAdapter<Place>) recyclerView.getAdapter());
@@ -103,7 +106,7 @@ public void updateNearbyListSignificantly() {
     /**
      * While nearby updates for current location held with bundle, automatically, custom updates are
      * done by calling this methods, triddered by search this are button input from user.
-     * @param placeList
+     * @param placeList List of nearby places to be added list fragment
      */
     public void updateNearbyListSignificantlyForCustomLocation(List<Place> placeList) {
         try {
@@ -113,6 +116,13 @@ public void updateNearbyListSignificantlyForCustomLocation(List<Place> placeList
         }
     }
 
+    /**
+     * When user moved too much, we need to update nearby list too. This operation is made by passing
+     * a bundle from NearbyFragment to NearbyListFragment and NearbyMapFragment. This method extracts
+     * place list from bundle to a list variable.
+     * @param bundle Bundle passed from NearbyFragment on users significant moving
+     * @return List of new nearby places
+     */
     private List<Place> getPlaceListFromBundle(Bundle bundle) {
         List<Place> placeList = Collections.emptyList();
 
@@ -176,6 +186,10 @@ public void onActivityResult(int requestCode, int resultCode, Intent data) {
         }
     }
 
+    /**
+     * Sets bundles for updates in map. Ie. user is moved too much so we need to update nearby markers.
+     * @param bundleForUpdates includes new calculated nearby places.
+     */
     public void setBundleForUpdates(Bundle bundleForUpdates) {
         this.bundleForUpdates = bundleForUpdates;
     }

app/src/main/java/fr/free/nrw/commons/nearby/NearbyMapFragment.java

@@ -15,7 +15,6 @@
 import android.support.design.widget.CoordinatorLayout;
 import android.support.design.widget.FloatingActionButton;
 import android.support.v7.app.AlertDialog;
-import android.util.Log;
 import android.view.Gravity;
 import android.view.KeyEvent;
 import android.view.LayoutInflater;
@@ -62,7 +61,7 @@
 import fr.free.nrw.commons.auth.LoginActivity;
 import fr.free.nrw.commons.bookmarks.locations.BookmarkLocationsDao;
 import fr.free.nrw.commons.contributions.ContributionController;
-import fr.free.nrw.commons.location.LocationServiceManager;
+
 import fr.free.nrw.commons.utils.LocationUtils;
 import fr.free.nrw.commons.utils.PlaceUtils;
 import fr.free.nrw.commons.utils.UriDeserializer;
@@ -130,7 +129,6 @@ public class NearbyMapFragment extends DaggerFragment {
     private final double CAMERA_TARGET_SHIFT_FACTOR_PORTRAIT = 0.06;
     private final double CAMERA_TARGET_SHIFT_FACTOR_LANDSCAPE = 0.04;
 
-    private boolean isMapReady;
     public boolean searchThisAreaModeOn = false;
 
     private Bundle bundleForUpdtes;// Carry information from activity about changed nearby places and current location
@@ -361,7 +359,10 @@ private void updateMapToTrackPosition() {
             }
         }
     }
-    
+
+    /**
+     * Initialize all views. TODO: Use bind view instead.
+     */
     private void initViews() {
         Timber.d("initViews called");
         bottomSheetList = ((NearbyFragment)getParentFragment()).view.findViewById(R.id.bottom_sheet);
@@ -406,6 +407,9 @@ private void initViews() {
 
     }
 
+    /**
+     * Sets click listeners of FABs, and 2 bottom sheets
+     */
     private void setListeners() {
         fabPlus.setOnClickListener(view -> {
             if (applicationPrefs.getBoolean("login_skipped", false)) {
@@ -512,6 +516,10 @@ public void onSlide(@NonNull View bottomSheet, float slideOffset) {
         }
     }
 
+    /**
+     * Sets up map view of first time it created, it passes MapBoxMap options and style assets.
+     * @param savedInstanceState bundle coming from Nearby Fragment
+     */
     private void setupMapView(Bundle savedInstanceState) {
         Timber.d("setupMapView called");
         MapboxMapOptions options = new MapboxMapOptions()
@@ -541,6 +549,10 @@ public void onMapReady(MapboxMap mapboxMap) {
         }
     }
 
+    /**
+     * Adds map movement listener to understand swiping with fingers. So that we can display search
+     * this area button to search nearby places for other locations
+     */
     private void addMapMovementListeners() {
 
         mapboxMap.addOnCameraMoveListener(new MapboxMap.OnCameraMoveListener() {
@@ -793,9 +805,7 @@ private void showFAB() {
         addAnchorToSmallFABs(fabGallery, ((NearbyFragment)getParentFragment()).view.findViewById(R.id.empty_view).getId());
 
         addAnchorToSmallFABs(fabCamera, ((NearbyFragment)getParentFragment()).view.findViewById(R.id.empty_view1).getId());
-
-        isMapReady = true;
-    }
+        }
 
 
     /*
@@ -946,6 +956,10 @@ private void openWebView(Uri link) {
         Utils.handleWebUrl(getContext(), link);
     }
 
+    /**
+     * Starts animation of fab plus (turning on opening) and other FABs
+     * @param isFabOpen state of FAB buttons, open when clicked on fab button, closed on other click
+     */
     private void animateFAB(boolean isFabOpen) {
             this.isFabOpen = !isFabOpen;
         if (fabPlus.isShown()){
@@ -966,6 +980,10 @@ private void animateFAB(boolean isFabOpen) {
         }
     }
 
+    /**
+     * Hides camera and gallery FABs, turn back plus FAB
+     * @param isFabOpen
+     */
     private void closeFabs ( boolean isFabOpen){
         if (isFabOpen) {
             fabPlus.startAnimation(rotate_backward);