Refactoring: fix Javadoc strings and style in cgCache

2 files changed, 42 insertions, 66 deletions

diff --git a/main/src/cgeo/geocaching/cgCache.java b/main/src/cgeo/geocaching/cgCache.java
index 33ada73..6ec1e6b 100644
--- a/main/src/cgeo/geocaching/cgCache.java
+++ b/main/src/cgeo/geocaching/cgCache.java
@@ -298,7 +298,7 @@ public class cgCache implements ICache, IWaypoint {
     /**
      * Compare two caches quickly. For map and list fields only the references are compared !
      *
-     * @param other
+     * @param other the other cache to compare this one to
      * @return true if both caches have the same content
      */
     private boolean isEqualTo(final cgCache other) {
@@ -373,21 +373,14 @@ public class cgCache implements ICache, IWaypoint {
     }
 
     /**
-     * checks if a page contains the guid of a cache
+     * Checks if a page contains the guid of a cache
      *
-     * @param cache
-     *            the cache to look for
      * @param page
-     *            the page to search in
-     *
-     * @return true: page contains guid of cache, false: otherwise
+     *            the page to search in, may be null
+     * @return true if the page contains the guid of the cache, false otherwise
      */
     public boolean isGuidContainedInPage(final String page) {
-        if (StringUtils.isBlank(page)) {
-            return false;
-        }
-        // check if the guid of the cache is anywhere in the page
-        if (StringUtils.isBlank(guid)) {
+        if (StringUtils.isBlank(page) || StringUtils.isBlank(guid)) {
             return false;
         }
         final Boolean found = Pattern.compile(guid, Pattern.CASE_INSENSITIVE).matcher(page).find();
@@ -399,10 +392,10 @@ public class cgCache implements ICache, IWaypoint {
         return cacheType.isEvent();
     }
 
-    public boolean logVisit(IAbstractActivity fromActivity) {
+    public void logVisit(final IAbstractActivity fromActivity) {
         if (StringUtils.isBlank(cacheId)) {
             fromActivity.showToast(((Activity) fromActivity).getResources().getString(R.string.err_cannot_log_visit));
-            return true;
+            return;
         }
         Intent logVisitIntent = new Intent((Activity) fromActivity, VisitCacheActivity.class);
         logVisitIntent.putExtra(VisitCacheActivity.EXTRAS_ID, cacheId);
@@ -410,18 +403,12 @@ public class cgCache implements ICache, IWaypoint {
         logVisitIntent.putExtra(VisitCacheActivity.EXTRAS_FOUND, found);
 
         ((Activity) fromActivity).startActivity(logVisitIntent);
-
-        return true;
     }
 
-    public boolean logOffline(final IAbstractActivity fromActivity, final LogType logType) {
-        String log = "";
-        if (StringUtils.isNotBlank(Settings.getSignature())
-                && Settings.isAutoInsertSignature()) {
-            log = LogTemplateProvider.applyTemplates(Settings.getSignature(), true);
-        }
-        logOffline(fromActivity, log, Calendar.getInstance(), logType);
-        return true;
+    public void logOffline(final IAbstractActivity fromActivity, final LogType logType) {
+        final boolean mustIncludeSignature = StringUtils.isNotBlank(Settings.getSignature()) && Settings.isAutoInsertSignature();
+        final String initial = mustIncludeSignature ? LogTemplateProvider.applyTemplates(Settings.getSignature(), true) : "";
+        logOffline(fromActivity, initial, Calendar.getInstance(), logType);
     }
 
     void logOffline(final IAbstractActivity fromActivity, final String log, Calendar date, final LogType logType) {
@@ -921,11 +908,7 @@ public class cgCache implements ICache, IWaypoint {
             }
         }
 
-        if (saveToDatabase) {
-            return cgeoapplication.getInstance().saveWaypoints(geocode, waypoints, false);
-        }
-
-        return false;
+        return saveToDatabase && cgeoapplication.getInstance().saveWaypoints(geocode, waypoints, false);
     }
 
     public List<LogEntry> getLogs() {
@@ -1116,8 +1099,8 @@ public class cgCache implements ICache, IWaypoint {
      * @param storageLocation
      *            the storageLocation to set
      */
-    public void addStorageLocation(StorageLocation sl) {
-        this.storageLocation.add(sl);
+    public void addStorageLocation(final StorageLocation storageLocation) {
+        this.storageLocation.add(storageLocation);
     }
 
     /**
@@ -1150,11 +1133,7 @@ public class cgCache implements ICache, IWaypoint {
             resetFinalDefined();
         }
 
-        if (saveToDatabase) {
-            return cgeoapplication.getInstance().saveOwnWaypoint(waypoint.getId(), geocode, waypoint);
-        }
-
-        return false;
+        return saveToDatabase && cgeoapplication.getInstance().saveOwnWaypoint(waypoint.getId(), geocode, waypoint);
     }
 
     public boolean hasWaypoints() {
@@ -1192,10 +1171,12 @@ public class cgCache implements ICache, IWaypoint {
     }
 
     /**
-     * @param index
-     * @return <code>true</code>, if the waypoint was duplicated
+     * Duplicate a waypoint.
+     *
+     * @param index the waypoint to duplicate
+     * @return <code>true</code> if the waypoint was duplicated, <code>false</code> otherwise (invalid index)
      */
-    public boolean duplicateWaypoint(int index) {
+    public boolean duplicateWaypoint(final int index) {
         if (!isValidWaypointIndex(index)) {
             return false;
         }
@@ -1206,11 +1187,8 @@ public class cgCache implements ICache, IWaypoint {
         return cgeoapplication.getInstance().saveOwnWaypoint(-1, geocode, copy);
     }
 
-    private boolean isValidWaypointIndex(int index) {
-        if (!hasWaypoints()) {
-            return false;
-        }
-        return index >= 0 && index < waypoints.size();
+    private boolean isValidWaypointIndex(final int index) {
+        return hasWaypoints() && index >= 0 && index < waypoints.size();
     }
 
     /**
@@ -1220,7 +1198,7 @@ public class cgCache implements ICache, IWaypoint {
      *            of the waypoint in cache's waypoint list
      * @return <code>true</code>, if the waypoint was deleted
      */
-    public boolean deleteWaypoint(int index) {
+    public boolean deleteWaypoint(final int index) {
         if (!isValidWaypointIndex(index)) {
             return false;
         }
@@ -1245,17 +1223,13 @@ public class cgCache implements ICache, IWaypoint {
      *            to be removed from cache
      * @return <code>true</code>, if the waypoint was deleted
      */
-    public boolean deleteWaypoint(cgWaypoint waypoint) {
+    public boolean deleteWaypoint(final cgWaypoint waypoint) {
         if (waypoint.getId() <= 0) {
             return false;
         }
 
         final int index = getWaypointIndex(waypoint);
-        if (index >= 0) {
-            return deleteWaypoint(index);
-        }
-
-        return false;
+        return index >= 0 && deleteWaypoint(index);
     }
 
     /**
@@ -1263,26 +1237,25 @@ public class cgCache implements ICache, IWaypoint {
      *
      * @param waypoint
      *            to find index for
-     * @return index in <code>waypoints</code> if found, else -1
+     * @return index in <code>waypoints</code> if found, -1 otherwise
      */
-    private int getWaypointIndex(cgWaypoint waypoint) {
-        int index = 0;
-
-        for (cgWaypoint wp : waypoints) {
-            if (wp.getId() == waypoint.getId()) {
+    private int getWaypointIndex(final cgWaypoint waypoint) {
+        final int id = waypoint.getId();
+        for (int index = 0; index < waypoints.size(); index++) {
+            if (waypoints.get(index).getId() == id) {
                 return index;
             }
-            index++;
         }
-
         return -1;
     }
 
     /**
-     * @param index
-     * @return waypoint or <code>null</code>
+     * Retrieve a given waypoint.
+     *
+     * @param index the index of the waypoint
+     * @return waypoint or <code>null</code> if index is out of range
      */
-    public cgWaypoint getWaypoint(int index) {
+    public cgWaypoint getWaypoint(final int index) {
         if (!isValidWaypointIndex(index)) {
             return null;
         }
@@ -1290,11 +1263,13 @@ public class cgCache implements ICache, IWaypoint {
     }
 
     /**
-     * @param index
+     * Lookup a waypoint by its id.
+     *
+     * @param id the id of the waypoint to look for
      * @return waypoint or <code>null</code>
      */
-    public cgWaypoint getWaypointById(int id) {
-        for (cgWaypoint waypoint : waypoints) {
+    public cgWaypoint getWaypointById(final int id) {
+        for (final cgWaypoint waypoint : waypoints) {
             if (waypoint.getId() == id) {
                 return waypoint;
             }
diff --git a/main/src/cgeo/geocaching/cgeocaches.java b/main/src/cgeo/geocaching/cgeocaches.java
index 197c452..070e115 100644
--- a/main/src/cgeo/geocaching/cgeocaches.java
+++ b/main/src/cgeo/geocaching/cgeocaches.java
@@ -1087,7 +1087,8 @@ public class cgeocaches extends AbstractListActivity {
             NavigationAppFactory.showNavigationMenu(geo, this, cache, null, null);
             return true;
         } else if (id == MENU_LOG_VISIT) {
-            return getCacheFromAdapter(adapterInfo).logVisit(this);
+            getCacheFromAdapter(adapterInfo).logVisit(this);
+            return true;
         } else if (id == MENU_CACHE_DETAILS) {
             final Intent cachesIntent = new Intent(this, CacheDetailActivity.class);
             final cgCache cache = getCacheFromAdapter(adapterInfo);