diff --git a/app/src/main/java/fr/free/nrw/commons/AboutActivity.java b/app/src/main/java/fr/free/nrw/commons/AboutActivity.java index 0ef5fa1716..6ed1bba1d9 100644 --- a/app/src/main/java/fr/free/nrw/commons/AboutActivity.java +++ b/app/src/main/java/fr/free/nrw/commons/AboutActivity.java @@ -8,10 +8,18 @@ import fr.free.nrw.commons.theme.NavigationBaseActivity; import fr.free.nrw.commons.ui.widget.HtmlTextView; +/** + * Represents about screen of this app + */ public class AboutActivity extends NavigationBaseActivity { @BindView(R.id.about_version) TextView versionText; @BindView(R.id.about_license) HtmlTextView aboutLicenseText; + /** + * This method helps in the creation About screen + * + * @param savedInstanceState Data bundle + */ @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); diff --git a/app/src/main/java/fr/free/nrw/commons/CommonsApplication.java b/app/src/main/java/fr/free/nrw/commons/CommonsApplication.java index 9a7b94a993..ee0f100193 100644 --- a/app/src/main/java/fr/free/nrw/commons/CommonsApplication.java +++ b/app/src/main/java/fr/free/nrw/commons/CommonsApplication.java @@ -49,16 +49,21 @@ public class CommonsApplication extends DaggerApplication { @Inject @Named("default_preferences") SharedPreferences defaultPrefs; @Inject @Named("application_preferences") SharedPreferences applicationPrefs; @Inject @Named("prefs") SharedPreferences otherPrefs; - + public static final String DEFAULT_EDIT_SUMMARY = "Uploaded using Android Commons app"; - + public static final String FEEDBACK_EMAIL = "commons-app-android@googlegroups.com"; + public static final String LOGS_PRIVATE_EMAIL = "commons-app-android-private@googlegroups.com"; + public static final String FEEDBACK_EMAIL_SUBJECT = "Commons Android App (%s) Feedback"; - + private CommonsApplicationComponent component; private RefWatcher refWatcher; + /** + * Used to declare and initialize various components and dependencies + */ @Override public void onCreate() { super.onCreate(); @@ -80,23 +85,41 @@ public void onCreate() { System.setProperty("in.yuvi.http.fluent.PROGRESS_TRIGGER_THRESHOLD", "3.0"); } + /** + * Helps in setting up LeakCanary library + * @return instance of LeakCanary + */ protected RefWatcher setupLeakCanary() { if (LeakCanary.isInAnalyzerProcess(this)) { return RefWatcher.DISABLED; } return LeakCanary.install(this); } - + + /** + * Provides a way to get member refWatcher + * + * @param context Application context + * @return application member refWatcher + */ public static RefWatcher getRefWatcher(Context context) { CommonsApplication application = (CommonsApplication) context.getApplicationContext(); return application.refWatcher; } - + + /** + * Helps in injecting dependency library Dagger + * @return Dagger injector + */ @Override - protected AndroidInjector applicationInjector() { + protected AndroidInjector applicationInjector() { return injector(); } + /** + * used to create injector of application component + * @return Application component of Dagger + */ public CommonsApplicationComponent injector() { if (component == null) { component = DaggerCommonsApplicationComponent.builder() @@ -106,6 +129,11 @@ public CommonsApplicationComponent injector() { return component; } + /** + * clears data of current application + * @param context Application context + * @param logoutListener Implementation of interface LogoutListener + */ public void clearApplicationData(Context context, LogoutListener logoutListener) { File cacheDirectory = context.getCacheDir(); File applicationDirectory = new File(cacheDirectory.getParent()); @@ -145,6 +173,9 @@ private void updateAllDatabases() { Contribution.Table.onDelete(db); } + /** + * Interface used to get log-out events + */ public interface LogoutListener { void onLogoutComplete(); } diff --git a/app/src/main/java/fr/free/nrw/commons/License.java b/app/src/main/java/fr/free/nrw/commons/License.java index 7b75cfda8c..db893de16f 100644 --- a/app/src/main/java/fr/free/nrw/commons/License.java +++ b/app/src/main/java/fr/free/nrw/commons/License.java @@ -2,6 +2,9 @@ import android.support.annotation.Nullable; +/** + * represents Licence object + */ public class License { private String key; private String template; @@ -56,6 +59,12 @@ public String getName() { } } + /** + * Gets the license URL + * + * @param language license language + * @return URL + */ public @Nullable String getUrl(String language) { if (url == null) { return null; diff --git a/app/src/main/java/fr/free/nrw/commons/LicenseList.java b/app/src/main/java/fr/free/nrw/commons/LicenseList.java index ab32f8815a..d08e314cca 100644 --- a/app/src/main/java/fr/free/nrw/commons/LicenseList.java +++ b/app/src/main/java/fr/free/nrw/commons/LicenseList.java @@ -13,10 +13,18 @@ import java.util.Locale; import java.util.Map; +/** + * Represents a list of Licenses + */ public class LicenseList { private Map licenses = new HashMap<>(); private Resources res; + /** + * Constructs new instance of LicenceList + * + * @param activity License activity + */ public LicenseList(Activity activity) { res = activity.getResources(); XmlPullParser parser = res.getXml(R.xml.wikimedia_licenses); @@ -31,14 +39,28 @@ public LicenseList(Activity activity) { } } + /** + * Gets a collection of licenses + * @return License values + */ public Collection values() { return licenses.values(); } + /** + * Gets license + * @param key License key + * @return License that matches key + */ public License get(String key) { return licenses.get(key); } + /** + * Creates a license from template + * @param template License template + * @return null + */ @Nullable License licenseForTemplate(String template) { String ucTemplate = new PageTitle(template).getDisplayText(); @@ -50,6 +72,11 @@ License licenseForTemplate(String template) { return null; } + /** + * Gets template name id + * @param template License template + * @return name id of template + */ private String nameIdForTemplate(String template) { // hack :D (converts dashes and periods to underscores) // cc-by-sa-3.0 -> cc_by_sa_3_0 @@ -57,6 +84,11 @@ private String nameIdForTemplate(String template) { "_").replace(".", "_"); } + /** + * Gets name of given template + * @param template License template + * @return name of template + */ private String nameForTemplate(String template) { int nameId = res.getIdentifier("fr.free.nrw.commons:string/" + nameIdForTemplate(template), null, null); @@ -92,4 +124,4 @@ private boolean xmlFastForward(XmlPullParser parser, String namespace, String el } } -} \ No newline at end of file +} diff --git a/app/src/main/java/fr/free/nrw/commons/Media.java b/app/src/main/java/fr/free/nrw/commons/Media.java index c75aae2a52..726d787f3e 100644 --- a/app/src/main/java/fr/free/nrw/commons/Media.java +++ b/app/src/main/java/fr/free/nrw/commons/Media.java @@ -47,16 +47,35 @@ public Media[] newArray(int i) { private HashMap tags = new HashMap<>(); private @Nullable LatLng coordinates; + /** + * Provides local constructor + */ protected Media() { this.categories = new ArrayList<>(); this.descriptions = new HashMap<>(); } + /** + * Provides a minimal constructor + * + * @param filename Media filename + */ public Media(String filename) { this(); this.filename = filename; } + /** + * Provide Media constructor + * @param localUri Media URI + * @param imageUrl Media image URL + * @param filename Media filename + * @param description Media description + * @param dataLength Media date length + * @param dateCreated Media creation date + * @param dateUploaded Media date uploaded + * @param creator Media creator + */ public Media(Uri localUri, String imageUrl, String filename, String description, long dataLength, Date dateCreated, @Nullable Date dateUploaded, String creator) { this(); @@ -90,19 +109,33 @@ public Media(Parcel in) { descriptions = in.readHashMap(ClassLoader.getSystemClassLoader()); } + /** + * Gets tag of media + * @param key Media key + * @return Media tag + */ public Object getTag(String key) { return tags.get(key); } + /** + * Modifies( or creates a) tag of media + * @param key Media key + * @param value Media value + */ public void setTag(String key, Object value) { tags.put(key, value); } + /** + * Gets media display title + * @return Media title + */ public String getDisplayTitle() { if (filename == null) { return ""; } - // FIXME: Gross hack bercause my regex skills suck maybe or I am too lazy who knows + // FIXME: Gross hack because my regex skills suck maybe or I am too lazy who knows String title = getFilePageTitle().getDisplayText().replaceFirst("^File:", ""); Matcher matcher = displayTitlePattern.matcher(title); if (matcher.matches()) { @@ -112,14 +145,27 @@ public String getDisplayTitle() { } } + /** + * Gets file page title + * @return New media page title + */ public PageTitle getFilePageTitle() { return new PageTitle("File:" + getFilename().replaceFirst("^File:", "")); } + /** + * Gets local URI + * @return Media local URI + */ public Uri getLocalUri() { return localUri; } + /** + * Gets image URL + * can be null. + * @return Image URL + */ @Nullable public String getImageUrl() { if (imageUrl == null && this.getFilename() != null) { @@ -304,6 +350,10 @@ public void setCategories(List categories) { this.categories.addAll(categories); } + /** + * Modifies (or sets) media descriptions + * @param descriptions Media descriptions + */ void setDescriptions(Map descriptions) { for (String key : this.descriptions.keySet()) { this.descriptions.remove(key); @@ -313,6 +363,11 @@ void setDescriptions(Map descriptions) { } } + /** + * Gets media description in preferred language + * @param preferredLanguage Language preferred + * @return Description in preferred language + */ public String getDescription(String preferredLanguage) { if (descriptions.containsKey(preferredLanguage)) { // See if the requested language is there. @@ -329,11 +384,21 @@ public String getDescription(String preferredLanguage) { } } + /** + * Method of Parcelable interface + * @return zero + */ @Override public int describeContents() { return 0; } + /** + * Creates a way to transfer information between two or more + * activities. + * @param parcel Instance of Parcel + * @param flags Parcel flag + */ @Override public void writeToParcel(Parcel parcel, int flags) { parcel.writeParcelable(localUri, flags); diff --git a/app/src/main/java/fr/free/nrw/commons/Utils.java b/app/src/main/java/fr/free/nrw/commons/Utils.java index 87dab7f680..967f2cf8ea 100644 --- a/app/src/main/java/fr/free/nrw/commons/Utils.java +++ b/app/src/main/java/fr/free/nrw/commons/Utils.java @@ -37,12 +37,23 @@ public static String stripLocalizedString(String s) { } } + /** + * Creates an URL for thumbnail + * + * @param filename Thumbnail file name + * @return URL of thumbnail + */ public static String makeThumbBaseUrl(@NonNull String filename) { String name = new PageTitle(filename).getPrefixedText(); String sha = new String(Hex.encodeHex(DigestUtils.md5(name))); return String.format("%s/%s/%s/%s", BuildConfig.IMAGE_URL_BASE, sha.substring(0, 1), sha.substring(0, 2), urlEncode(name)); } + /** + * URL Encode an URL in UTF-8 format + * @param url Unformatted URL + * @return Encoded URL + */ public static String urlEncode(String url) { try { return URLEncoder.encode(url, "utf-8"); @@ -61,6 +72,11 @@ public static String capitalize(String string) { return string.substring(0, 1).toUpperCase(Locale.getDefault()) + string.substring(1); } + /** + * Generates licence name with given ID + * @param license License ID + * @return Name of license + */ public static int licenseNameFor(String license) { switch (license) { case Prefs.Licenses.CC_BY_3: @@ -81,6 +97,12 @@ public static int licenseNameFor(String license) { throw new RuntimeException("Unrecognized license value: " + license); } + /** + * Fixing incorrect extension + * @param title File name + * @param extension Correct extension + * @return File with correct extension + */ public static String fixExtension(String title, String extension) { Pattern jpegPattern = Pattern.compile("\\.jpeg$", Pattern.CASE_INSENSITIVE); @@ -96,6 +118,11 @@ public static String fixExtension(String title, String extension) { return title; } + /** + * Tells whether dark theme is active or not + * @param context Activity context + * @return The state of dark theme + */ public static boolean isDarkTheme(Context context) { return PreferenceManager.getDefaultSharedPreferences(context).getBoolean("theme", false); } diff --git a/app/src/main/java/fr/free/nrw/commons/WelcomeActivity.java b/app/src/main/java/fr/free/nrw/commons/WelcomeActivity.java index f6c5999e98..7bfb22890d 100644 --- a/app/src/main/java/fr/free/nrw/commons/WelcomeActivity.java +++ b/app/src/main/java/fr/free/nrw/commons/WelcomeActivity.java @@ -18,6 +18,11 @@ public class WelcomeActivity extends BaseActivity { private WelcomePagerAdapter adapter = new WelcomePagerAdapter(); + /** + * Initialises exiting fields and dependencies + * + * @param savedInstanceState WelcomeActivity bundled data + */ @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); @@ -30,12 +35,20 @@ public void onCreate(Bundle savedInstanceState) { adapter.setCallback(this::finish); } + /** + * References WelcomePageAdapter to null before the activity is destroyed + */ @Override public void onDestroy() { adapter.setCallback(null); super.onDestroy(); } + /** + * Creates a way to change current activity to WelcomeActivity + * + * @param context Activity context + */ public static void startYourself(Context context) { Intent welcomeIntent = new Intent(context, WelcomeActivity.class); context.startActivity(welcomeIntent); diff --git a/app/src/main/java/fr/free/nrw/commons/WelcomePagerAdapter.java b/app/src/main/java/fr/free/nrw/commons/WelcomePagerAdapter.java index 9669196e98..a346655cfc 100644 --- a/app/src/main/java/fr/free/nrw/commons/WelcomePagerAdapter.java +++ b/app/src/main/java/fr/free/nrw/commons/WelcomePagerAdapter.java @@ -10,13 +10,6 @@ import butterknife.OnClick; public class WelcomePagerAdapter extends PagerAdapter { - private static final int PAGE_FINAL = 4; - private Callback callback; - - public interface Callback { - void onYesClicked(); - } - static final int[] PAGE_LAYOUTS = new int[]{ R.layout.welcome_wikipedia, R.layout.welcome_do_upload, @@ -24,16 +17,34 @@ public interface Callback { R.layout.welcome_image_details, R.layout.welcome_final }; + private static final int PAGE_FINAL = 4; + private Callback callback; + /** + * Changes callback to provided one + * + * @param callback New callback + * it can be null. + */ public void setCallback(@Nullable Callback callback) { this.callback = callback; } + /** + * Gets total number of layouts + * @return Number of layouts + */ @Override public int getCount() { return PAGE_LAYOUTS.length; } + /** + * Compares given view with provided object + * @param view Adapter view + * @param object Adapter object + * @return Equality between view and object + */ @Override public boolean isViewFromObject(View view, Object object) { return (view == object); @@ -52,16 +63,29 @@ public Object instantiateItem(ViewGroup container, int position) { return layout; } + /** + * Provides a way to remove an item from container + * @param container Adapter view group container + * @param position Index of item + * @param obj Adapter object + */ @Override public void destroyItem(ViewGroup container, int position, Object obj) { container.removeView((View) obj); } + public interface Callback { + void onYesClicked(); + } + class ViewHolder { ViewHolder(View view) { ButterKnife.bind(this, view); } + /** + * Triggers on click callback on button click + */ @OnClick(R.id.welcomeYesButton) void onClicked() { if (callback != null) { diff --git a/app/src/main/java/fr/free/nrw/commons/data/Category.java b/app/src/main/java/fr/free/nrw/commons/data/Category.java index 757f6b6914..be4a298465 100644 --- a/app/src/main/java/fr/free/nrw/commons/data/Category.java +++ b/app/src/main/java/fr/free/nrw/commons/data/Category.java @@ -14,6 +14,9 @@ import fr.free.nrw.commons.category.CategoryContentProvider; +/** + * Represents a category + */ public class Category { private Uri contentUri; @@ -22,36 +25,72 @@ public class Category { private int timesUsed; // Getters/setters + /** + * Gets name + * + * @return name + */ public String getName() { return name; } + /** + * Modifies name + * + * @param name Category name + */ public void setName(String name) { this.name = name; } + /** + * Gets last used date + * + * @return Last used date + */ private Date getLastUsed() { // warning: Date objects are mutable. return (Date)lastUsed.clone(); } + /** + * Modifies last used date + * + * @param lastUsed Category date + */ public void setLastUsed(Date lastUsed) { // warning: Date objects are mutable. this.lastUsed = (Date)lastUsed.clone(); } + /** + * Generates new last used date + */ private void touch() { lastUsed = new Date(); } + /** + * Gets no. of times the category is used + * + * @return no. of times used + */ private int getTimesUsed() { return timesUsed; } + /** + * Modifies no. of times used + * + * @param timesUsed Category used times + */ public void setTimesUsed(int timesUsed) { this.timesUsed = timesUsed; } + /** + * Increments timesUsed by 1 and sets last used date as now. + */ public void incTimesUsed() { timesUsed++; touch(); @@ -75,6 +114,11 @@ public void save(ContentProviderClient client) { } } + /** + * Gets content values + * + * @return Content values + */ private ContentValues toContentValues() { ContentValues cv = new ContentValues(); cv.put(Table.COLUMN_NAME, getName()); @@ -83,6 +127,11 @@ private ContentValues toContentValues() { return cv; } + /** + * Gets category from cursor + * @param cursor Category cursor + * @return Category from cursor + */ private static Category fromCursor(Cursor cursor) { // Hardcoding column positions! Category c = new Category(); @@ -175,15 +224,30 @@ public static class Table { + COLUMN_TIMES_USED + " INTEGER" + ");"; + /** + * Creates new table with provided SQLite database + * + * @param db Category database + */ public static void onCreate(SQLiteDatabase db) { db.execSQL(CREATE_TABLE_STATEMENT); } + /** + * Deletes existing table + * @param db Category database + */ public static void onDelete(SQLiteDatabase db) { db.execSQL("DROP TABLE IF EXISTS " + TABLE_NAME); onCreate(db); } + /** + * Updates given database + * @param db Category database + * @param from Exiting category id + * @param to New category id + */ public static void onUpdate(SQLiteDatabase db, int from, int to) { if (from == to) { return; @@ -209,4 +273,4 @@ public static void onUpdate(SQLiteDatabase db, int from, int to) { } } //endregion -} +} \ No newline at end of file diff --git a/app/src/main/java/fr/free/nrw/commons/mwapi/LogBuilder.java b/app/src/main/java/fr/free/nrw/commons/mwapi/LogBuilder.java index 7a4b294fa0..2a2456cc38 100644 --- a/app/src/main/java/fr/free/nrw/commons/mwapi/LogBuilder.java +++ b/app/src/main/java/fr/free/nrw/commons/mwapi/LogBuilder.java @@ -22,6 +22,14 @@ public class LogBuilder { private final String schema; private final SharedPreferences prefs; + /** + * Main constructor of LogBuilder + * + * @param schema Log schema + * @param revision Log revision + * @param mwApi Wiki media API instance + * @param prefs Instance of SharedPreferences + */ LogBuilder(String schema, long revision, MediaWikiApi mwApi, SharedPreferences prefs) { this.prefs = prefs; this.data = new JSONObject(); @@ -30,6 +38,12 @@ public class LogBuilder { this.mwApi = mwApi; } + /** + * Adds data to preferences + * @param key Log key + * @param value Log object value + * @return LogBuilder + */ public LogBuilder param(String key, Object value) { try { data.put(key, value); @@ -39,6 +53,10 @@ public LogBuilder param(String key, Object value) { return this; } + /** + * Encodes JSON object to URL + * @return URL to JSON object + */ URL toUrl() { JSONObject fullData = new JSONObject(); try { @@ -65,7 +83,7 @@ public void log(boolean force) { LogTask logTask = new LogTask(mwApi); logTask.executeOnExecutor(AsyncTask.THREAD_POOL_EXECUTOR, this); } - + public void log() { log(false); } diff --git a/app/src/main/java/fr/free/nrw/commons/mwapi/LogTask.java b/app/src/main/java/fr/free/nrw/commons/mwapi/LogTask.java index 3fce8aaf18..e564a50ab8 100644 --- a/app/src/main/java/fr/free/nrw/commons/mwapi/LogTask.java +++ b/app/src/main/java/fr/free/nrw/commons/mwapi/LogTask.java @@ -6,10 +6,20 @@ class LogTask extends AsyncTask { private final MediaWikiApi mwApi; + /** + * Main constructor of LogTask + * + * @param mwApi Media wiki API instance + */ public LogTask(MediaWikiApi mwApi) { this.mwApi = mwApi; } + /** + * Logs events in background + * @param logBuilders LogBuilder instance + * @return Background success state ( TRUE or FALSE ) + */ @Override protected Boolean doInBackground(LogBuilder... logBuilders) { return mwApi.logEvents(logBuilders); diff --git a/app/src/main/java/fr/free/nrw/commons/mwapi/MediaResult.java b/app/src/main/java/fr/free/nrw/commons/mwapi/MediaResult.java index cfddf8c153..f2f34ce6d4 100644 --- a/app/src/main/java/fr/free/nrw/commons/mwapi/MediaResult.java +++ b/app/src/main/java/fr/free/nrw/commons/mwapi/MediaResult.java @@ -4,15 +4,29 @@ public class MediaResult { private final String wikiSource; private final String parseTreeXmlSource; + /** + * Full-fledged constructor of MediaResult + * + * @param wikiSource Media wiki source + * @param parseTreeXmlSource Media tree parsed in XML + */ MediaResult(String wikiSource, String parseTreeXmlSource) { this.wikiSource = wikiSource; this.parseTreeXmlSource = parseTreeXmlSource; } + /** + * Gets wiki source + * @return Wiki source + */ public String getWikiSource() { return wikiSource; } + /** + * Gets tree parsed in XML + * @return XML parsed tree + */ public String getParseTreeXmlSource() { return parseTreeXmlSource; } diff --git a/app/src/main/java/fr/free/nrw/commons/mwapi/UploadResult.java b/app/src/main/java/fr/free/nrw/commons/mwapi/UploadResult.java index 34d050b2c2..9422497b3b 100644 --- a/app/src/main/java/fr/free/nrw/commons/mwapi/UploadResult.java +++ b/app/src/main/java/fr/free/nrw/commons/mwapi/UploadResult.java @@ -9,11 +9,24 @@ public class UploadResult { private String imageUrl; private String canonicalFilename; + /** + * Minimal constructor + * + * @param resultStatus Upload result status + * @param errorCode Upload error code + */ UploadResult(String resultStatus, String errorCode) { this.resultStatus = resultStatus; this.errorCode = errorCode; } + /** + * Full-fledged constructor + * @param resultStatus Upload result status + * @param dateUploaded Uploaded date + * @param canonicalFilename Uploaded file name + * @param imageUrl Uploaded image file name + */ UploadResult(String resultStatus, Date dateUploaded, String canonicalFilename, String imageUrl) { this.resultStatus = resultStatus; this.dateUploaded = dateUploaded; @@ -21,22 +34,42 @@ public class UploadResult { this.imageUrl = imageUrl; } + /** + * Gets uploaded date + * @return Upload date + */ public Date getDateUploaded() { return dateUploaded; } + /** + * Gets image url + * @return Uploaded image url + */ public String getImageUrl() { return imageUrl; } + /** + * Gets canonical file name + * @return Uploaded file name + */ public String getCanonicalFilename() { return canonicalFilename; } + /** + * Gets upload error code + * @return Error code + */ public String getErrorCode() { return errorCode; } + /** + * Gets upload result status + * @return Upload result status + */ public String getResultStatus() { return resultStatus; } diff --git a/app/src/main/java/fr/free/nrw/commons/utils/LengthUtils.java b/app/src/main/java/fr/free/nrw/commons/utils/LengthUtils.java index 6fd9f9612d..8b687164be 100644 --- a/app/src/main/java/fr/free/nrw/commons/utils/LengthUtils.java +++ b/app/src/main/java/fr/free/nrw/commons/utils/LengthUtils.java @@ -37,6 +37,13 @@ public static double computeDistanceBetween(LatLng from, LatLng to) { return computeAngleBetween(from, to) * 6371009.0D; // Earth's radius in meter } + /** + * Computes angle between two points + * + * @param from Point A + * @param to Point B + * @return Angle in radius + */ private static double computeAngleBetween(LatLng from, LatLng to) { return distanceRadians(Math.toRadians(from.getLatitude()), Math.toRadians(from.getLongitude()), @@ -44,18 +51,43 @@ private static double computeAngleBetween(LatLng from, LatLng to) { Math.toRadians(to.getLongitude())); } + /** + * Computes arc length between 2 points + * @param lat1 Latitude of point A + * @param lng1 Longitude of point A + * @param lat2 Latitude of point B + * @param lng2 Longitude of point B + * @return Arc length between the points + */ private static double distanceRadians(double lat1, double lng1, double lat2, double lng2) { return arcHav(havDistance(lat1, lat2, lng1 - lng2)); } + /** + * Computes inverse of haversine + * @param x Angle in radian + * @return Inverse of haversine + */ private static double arcHav(double x) { return 2.0D * Math.asin(Math.sqrt(x)); } + /** + * Computes distance between two points that are on same Longitude + * @param lat1 Latitude of point A + * @param lat2 Latitude of point B + * @param longitude Longitude on which they lie + * @return Arc length between points + */ private static double havDistance(double lat1, double lat2, double longitude) { return hav(lat1 - lat2) + hav(longitude) * Math.cos(lat1) * Math.cos(lat2); } + /** + * Computes haversine + * @param x Angle in radians + * @return Haversine of x + */ private static double hav(double x) { double sinHalf = Math.sin(x * 0.5D); return sinHalf * sinHalf;