Nearby offline pins: Add javadoc

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

@@ -33,6 +33,15 @@ public abstract class PlaceDao {
     @Query("SELECT * from place WHERE entityID=:entity")
     public abstract Place getPlace(String entity);
 
+    /**
+     * Retrieves a list of places within the specified rectangular area.
+     *
+     * @param latBegin Latitudinal lower bound
+     * @param lngBegin Longitudinal lower bound
+     * @param latEnd Latitudinal upper bound, should be greater than `latBegin`
+     * @param lngEnd Longitudinal upper bound, should be greater than `lngBegin`
+     * @return The list of places within the specified rectangular geographical area.
+     */
     @Query("SELECT * from place WHERE name!='' AND latitude>=:latBegin AND longitude>=:lngBegin "
         + "AND latitude<:latEnd AND longitude<:lngEnd")
     public abstract List<Place> fetchPlaces(double latBegin, double lngBegin,

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

@@ -30,6 +30,14 @@ public class PlacesLocalDataSource {
         return placeDao.getPlace(entityID);
     }
 
+    /**
+     * Retrieves a list of places from the database within the geographical area
+     * specified by map's opposite corners.
+     *
+     * @param mapBottomLeft Bottom left corner of the map.
+     * @param mapTopRight Top right corner of the map.
+     * @return The list of saved places within the map's view.
+     */
     public List<Place> fetchPlaces(final LatLng mapBottomLeft, final LatLng mapTopRight) {
         class Constraint {
 

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

@@ -40,6 +40,13 @@ public class PlacesRepository {
         return localDataSource.fetchPlace(entityID);
     }
 
+    /**
+     * Retrieves a list of places within the geographical area specified by map's opposite corners.
+     *
+     * @param mapBottomLeft Bottom left corner of the map.
+     * @param mapTopRight Top right corner of the map.
+     * @return The list of saved places within the map's view.
+     */
     public List<Place> fetchPlaces(final LatLng mapBottomLeft, final LatLng mapTopRight) {
         return localDataSource.fetchPlaces(mapBottomLeft, mapTopRight);
     }

app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.java

@@ -1039,6 +1039,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment
         };
     }
 
+    /**
+     * Updates the internet unavailable snackbar to reflect whether cached pins are shown.
+     *
+     * @param offlinePinsShown Whether there are pins currently being shown on map.
+     */
     @Override
     public void updateSnackbar(final boolean offlinePinsShown) {
         if (!isNetworkErrorOccurred || snackbar == null) {
@@ -1065,6 +1070,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment
         }
     }
 
+    /**
+     * Returns the location of the top right corner of the map view.
+     *
+     * @return a `LatLng` object denoting the location of the top right corner of the map.
+     */
     @Override
     public LatLng getScreenTopRight() {
         final IGeoPoint screenTopRight = binding.map.getProjection()
@@ -1073,6 +1083,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment
             screenTopRight.getLatitude(), screenTopRight.getLongitude(), 0);
     }
 
+    /**
+     * Returns the location of the bottom left corner of the map view.
+     *
+     * @return a `LatLng` object denoting the location of the bottom left corner of the map.
+     */
     @Override
     public LatLng getScreenBottomLeft() {
         final IGeoPoint screenBottomLeft = binding.map.getProjection()

app/src/main/java/fr/free/nrw/commons/nearby/presenter/NearbyParentFragmentPresenter.kt

@@ -492,6 +492,12 @@ class NearbyParentFragmentPresenter
         }
     }
 
+    /**
+     * Handles the map scroll user action for `NearbyParentFragment`
+     *
+     * @param scope The lifecycle scope of `nearbyParentFragment`'s `viewLifecycleOwner`
+     * @param isNetworkAvailable Whether to load pins from the internet or from the cache.
+     */
     @Override
     override fun handleMapScrolled(scope: LifecycleCoroutineScope?, isNetworkAvailable: Boolean) {
         scope ?: return