Merge pull request #19 from grumlimited/javadocs

v0.5.4
grumlimited · Feb 25, 2018 · 2f698b4 · 2f698b4
2 parents ec9719b + 42d8b86
commit 2f698b4
Show file tree

Hide file tree

Showing 11 changed files with 225 additions and 164 deletions.
diff --git a/README.md b/README.md
@@ -2,38 +2,35 @@ Java Geocalc ![alt text](https://api.travis-ci.org/grumlimited/geocalc.svg?branc
 =======
 
 Geocalc is a simple java library aimed at doing arithmetics with Earth coordinates. 
-It is designed to be simple to embed in your existing applications and easy to use. Geocalc can:
+It is designed to be simple to embed in your existing applications and easy to use. 
 
-1. Calculate the distance between two coordinates
+Geocalc can:
+
+1. Calculate the distance between two coordinates (law of cosines, harvesine and vincenty)
 2. Find a point at X distance from a standpoint, given a bearing
-3. Calculate a rectangular area around a point
+3. Calculate coordinates of a rectangular area around a point
 4. Determine whether a Point is contained within that area
-5. Calculate the azimuth and final bearings between two points
+5. Calculate the azimuth, initial and final bearings between two points (vincenty)
 
 This library is being used on [www.rentbarometer.com](http://www.rentbarometer.com).
 
 This library implements in Java lots of ideas from [Movable-Type](http://www.movable-type.co.uk/scripts/latlong.html). Many thanks.
 
-## Versions
+## Changelog
+
+### 0.5.4
+* added `EarthCalc.midPoint(p1, p2)`
+* renamed `EarthCalc.boundingArea()` to `EarthCalc.pointAt(...)`
+* renamed `BoundingArea.boundingArea()` to `BoundingArea.around(...)`
+* Removed `get...()` out of `Point` and `BoundingArea` 
+* added maven javadoc plugin
 
 ### 0.5.3
-* Changed constructors to default and private visibility
-* Removed `get...()` keyword out of `EarthCalc` methods 
+* changed constructors to default and private visibility
+* removed `get...()` keyword out of `EarthCalc` methods 
 * `EarthCalc.getDistance()` is now `EarthCalc.gcdDistance()`
-* Renamed `BoundingArea.isContainedWithin(...)` to `BoundingArea.contains(...)`
-
-## Installing
+* renamed `BoundingArea.isContainedWithin(...)` to `BoundingArea.contains(...)`
 
-### Download
-
-    git clone [email protected]:grumlimited/geocalc.git
-
-### Compile
-
-    mvn clean install -DskipTests=true
-
-You will need a JDK 1.8 and maven.
-
 ### Embed
 
     <repositories>
@@ -43,15 +40,20 @@ You will need a JDK 1.8 and maven.
         </repository>
     </repositories>
 
-#
 
     <dependency>
 	    <groupId>com.github.grumlimited</groupId>
 	    <artifactId>geocalc</artifactId>
-	    <version>v0.5.2</version>
+	    <version>v0.5.4</version>
 	</dependency>
 
-Please refer to [jitpack.io/#grumlimited/geocalc/0.5.3](https://jitpack.io/#grumlimited/geocalc/0.5.3) for more information
+Please refer to [jitpack.io/#grumlimited/geocalc/0.5.4](https://jitpack.io/#grumlimited/geocalc/0.5.4) for more information
+
+## API
+
+can be found here:
+
+[grumlimited.co.uk/geocalc/0.5.4](http://www.grumlimited.co.uk/geocalc/0.5.4)
 
 ## Usage
 
@@ -152,8 +154,8 @@ While this only gives an approximation, it is several order of magnitude faster
 than calculating the distances from each point in the set to the reference point.
 
       BoundingArea area = EarthCalc.boundingArea(kew, 3000);
-      Point nw = area.getNorthWest();
-      Point se = area.getSouthEast();
+      Point nw = area.northWest;
+      Point se = area.southEast;
       
 Now, given that rectangle delimited by 'nw' and 'se', you can determine which points in your set are within these boundaries.
 

diff --git a/pom.xml b/pom.xml
@@ -7,23 +7,63 @@
     <groupId>com.grum</groupId>
     <artifactId>geocalc</artifactId>
     <packaging>jar</packaging>
-    <version>0.5.3-SNAPSHOT</version>
-    <name>Geocalc</name>
+    <version>0.5.4</version>
+    <name>${project.groupId}.${project.artifactId}</name>
     <url>http://www.grumlimited.co.uk</url>
 
+    <description>Simple Geocalc Library</description>
+    <licenses>
+        <license>
+            <name>BSD 3-Clause License</name>
+        </license>
+    </licenses>
+    <organization>
+        <name>Grumlimited</name>
+        <url>http://www.grumlimited.co.uk</url>
+    </organization>
+    <developers>
+        <developer>
+            <name>GR211</name>
+            <email>romain.gallet__at__gmail.com</email>
+            <organization>Grum Limited</organization>
+            <organizationUrl>http://www.grumlimited.co.uk</organizationUrl>
+        </developer>
+        <developer>
+            <name>Blackleg</name>
+            <email>hectorespertpardo__at__gmail.com</email>
+            <organization>Blackleg</organization>
+            <organizationUrl>http://www.blackleg.es</organizationUrl>
+        </developer>
+    </developers>
+
     <prerequisites>
         <maven>3.0</maven>
     </prerequisites>
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.source>1.8</maven.compiler.source>
+        <maven.compiler.target>1.8</maven.compiler.target>
     </properties>
 
     <build>
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.0.0</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.3</version>
+                <version>3.6.0</version>
                 <configuration>
                     <source>1.8</source>
                     <target>1.8</target>
@@ -33,7 +73,7 @@
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>versions-maven-plugin</artifactId>
-                <version>2.1</version>
+                <version>2.3</version>
             </plugin>
         </plugins>
     </build>

diff --git a/src/main/java/com/grum/geocalc/BoundingArea.java b/src/main/java/com/grum/geocalc/BoundingArea.java
@@ -33,37 +33,21 @@
 package com.grum.geocalc;
 
 /**
- * Represents an area, defined by its top left and bottom right
+ * Represents an area (viewed rectangular shaped projected onto Earth), defined by its top left and bottom right
  * coordinates
  *
  * @author rgallet
  */
 public class BoundingArea {
-    private Point northEast, southWest;
-    private Point southEast, northWest;
+    public final Point northEast, southWest;
+    public final Point southEast, northWest;
 
     public BoundingArea(Point northEast, Point southWest) {
         this.northEast = northEast;
         this.southWest = southWest;
 
-        southEast = Point.at(Coordinate.fromDegrees(southWest.getLatitude()), Coordinate.fromDegrees(northEast.getLongitude()));
-        northWest = Point.at(Coordinate.fromDegrees(northEast.getLatitude()), Coordinate.fromDegrees(southWest.getLongitude()));
-    }
-
-    public Point getNorthEast() {
-        return northEast;
-    }
-
-    public Point getSouthWest() {
-        return southWest;
-    }
-
-    public Point getSouthEast() {
-        return southEast;
-    }
-
-    public Point getNorthWest() {
-        return northWest;
+        southEast = Point.at(Coordinate.fromDegrees(southWest.latitude), Coordinate.fromDegrees(northEast.longitude));
+        northWest = Point.at(Coordinate.fromDegrees(northEast.latitude), Coordinate.fromDegrees(southWest.longitude));
     }
 
     @Override
@@ -72,13 +56,18 @@ public String toString() {
     }
 
     /**
-     * @Deprecated use contains(Point point)
+     * @return true if Point point is contained withing this bounding area
+     * @deprecated use contains(Point point)
      */
     @Deprecated
     public boolean isContainedWithin(Point point) {
         return contains(point);
     }
 
+    /**
+     * @param point point to check
+     * @return true if Point point is contained withing this bounding area
+     */
     public boolean contains(Point point) {
         boolean predicate1 = point.latitude >= this.southWest.latitude && point.latitude <= this.northEast.latitude;
 

diff --git a/src/main/java/com/grum/geocalc/Coordinate.java b/src/main/java/com/grum/geocalc/Coordinate.java
@@ -39,20 +39,21 @@
 import static java.lang.Math.*;
 
 /**
- * Represent a coordinate decimalDegrees, in degrees
+ * Abstraction of coordinate systems (degrees, radians, dms and gps)
  *
  * @author rgallet
  */
 abstract public class Coordinate implements Serializable {
 
-    public abstract double getDecimalDegrees();
+    abstract double degrees();
 
     /**
-     * @Deprecated use getDecimalDegrees()
+     * @return degree value
+     * @deprecated use degrees()
      */
     @Deprecated
     public double getValue() {
-        return getDecimalDegrees();
+        return degrees();
     }
 
     public static DegreeCoordinate fromDegrees(double decimalDegrees) {
@@ -72,8 +73,8 @@ public static RadianCoordinate fromRadians(double radians) {
     }
 
     DMSCoordinate toDMSCoordinate() {
-        double _wholeDegrees = (int) getDecimalDegrees();
-        double remaining = abs(getDecimalDegrees() - _wholeDegrees);
+        double _wholeDegrees = (int) degrees();
+        double remaining = abs(degrees() - _wholeDegrees);
         double _minutes = (int) (remaining * 60);
         remaining = remaining * 60 - _minutes;
         double _seconds = new BigDecimal(remaining * 60).setScale(4, RoundingMode.HALF_UP).doubleValue();
@@ -82,18 +83,18 @@ DMSCoordinate toDMSCoordinate() {
     }
 
     DegreeCoordinate toDegreeCoordinate() {
-        return new DegreeCoordinate(getDecimalDegrees());
+        return new DegreeCoordinate(degrees());
     }
 
     GPSCoordinate toGPSCoordinate() {
-        double _wholeDegrees = floor(getDecimalDegrees());
-        double remaining = getDecimalDegrees() - _wholeDegrees;
+        double _wholeDegrees = floor(degrees());
+        double remaining = degrees() - _wholeDegrees;
         double _minutes = floor(remaining * 60);
 
         return new GPSCoordinate(_wholeDegrees, _minutes);
     }
 
     RadianCoordinate toRadianCoordinate() {
-        return new RadianCoordinate(toRadians(getDecimalDegrees()));
+        return new RadianCoordinate(toRadians(degrees()));
     }
 }
diff --git a/src/main/java/com/grum/geocalc/DMSCoordinate.java b/src/main/java/com/grum/geocalc/DMSCoordinate.java
@@ -51,8 +51,8 @@ public class DMSCoordinate extends Coordinate {
     }
 
     @Override
-    public double getDecimalDegrees() {
-        double decimalDegrees = abs(this.wholeDegrees) + minutes / 60 + seconds / 3600;
+    double degrees() {
+        double decimalDegrees = abs(wholeDegrees) + minutes / 60 + seconds / 3600;
 
         if (wholeDegrees < 0) {
             decimalDegrees = -decimalDegrees;
@@ -62,23 +62,26 @@ public double getDecimalDegrees() {
     }
 
     /**
-     * @Deprecated use minutes
+     * @return minutes
+     * @deprecated use minutes
      */
     @Deprecated
     public double getMinutes() {
         return minutes;
     }
 
     /**
-     * @Deprecated use wholeDegrees
+     * @return wholeDegrees
+     * @deprecated use wholeDegrees
      */
     @Deprecated
     public double getWholeDegrees() {
         return wholeDegrees;
     }
 
     /**
-     * @Deprecated use seconds
+     * @return seconds
+     * @deprecated use seconds
      */
     @Deprecated
     public double getSeconds() {

diff --git a/src/main/java/com/grum/geocalc/DegreeCoordinate.java b/src/main/java/com/grum/geocalc/DegreeCoordinate.java
@@ -47,7 +47,7 @@ public class DegreeCoordinate extends Coordinate {
     }
 
     @Override
-    public double getDecimalDegrees() {
+    double degrees() {
         return decimalDegrees;
     }