Skip to content

Commit c6e63d0

Browse files
davidmotendavidmoten
committed
update javadoc
1 parent ee1e0ef commit c6e63d0

File tree

5 files changed

+143
-96
lines changed

5 files changed

+143
-96
lines changed

‎pom.xml

+18-2
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
<cobertura.version>2.6</cobertura.version>
2525
<checkstyle.version>2.7</checkstyle.version>
2626
<findbugs.version>2.3.2</findbugs.version>
27-
<javadoc.version>2.9.1</javadoc.version>
27+
<javadoc.version>2.10.3</javadoc.version>
2828
<pmd.version>2.5</pmd.version>
2929
<jdepend.version>2.0-beta-2</jdepend.version>
3030
<javancss.version>2.0</javancss.version>
@@ -121,6 +121,22 @@
121121
<target>${maven.compiler.target}</target>
122122
</configuration>
123123
</plugin>
124+
<plugin>
125+
<groupId>org.apache.maven.plugins</groupId>
126+
<artifactId>maven-javadoc-plugin</artifactId>
127+
<version>${javadoc.version}</version>
128+
<executions>
129+
<execution>
130+
<id>attach-javadocs</id>
131+
<goals>
132+
<goal>jar</goal>
133+
</goals>
134+
<configuration>
135+
<additionalparam>-Xdoclint:none</additionalparam>
136+
</configuration>
137+
</execution>
138+
</executions>
139+
</plugin>
124140
<plugin>
125141
<artifactId>maven-site-plugin</artifactId>
126142
<version>${m3.site.version}</version>
@@ -206,7 +222,7 @@
206222
<plugin>
207223
<groupId>org.apache.maven.plugins</groupId>
208224
<artifactId>maven-javadoc-plugin</artifactId>
209-
<version>2.8.1</version>
225+
<version>${javadoc.version}</version>
210226
<configuration>
211227
<aggregate>true</aggregate>
212228
</configuration>

‎src/main/java/com/github/davidmoten/geo/GeoHash.java

+52-27
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,6 @@
1818
* <a href="http://en.wikipedia.org/wiki/Geohash">geohashing</a>.
1919
* </p>
2020
*
21-
* @author dave
22-
*
2321
*/
2422
public final class GeoHash {
2523

@@ -134,7 +132,10 @@ private static void addOddParityEntries(Map<Direction, Map<Parity, String>> m) {
134132
* borders too (at the poles and the -180,180 longitude boundaries).
135133
*
136134
* @param hash
135+
* string hash relative to which the adjacent is returned
137136
* @param direction
137+
* direction relative to {@code hash} for which the adjacent is
138+
* returned
138139
* @return hash of adjacent hash
139140
*/
140141
public static String adjacentHash(String hash, Direction direction) {
@@ -413,6 +414,7 @@ static long encodeHashToLong(double latitude, double longitude, int length) {
413414
* Latitude will be between -90 and 90 and longitude between -180 and 180.
414415
*
415416
* @param geohash
417+
* hash to decode
416418
* @return lat long point
417419
*/
418420
// Translated to java from:
@@ -471,10 +473,14 @@ private static void refineInterval(double[] interval, int cd, int mask) {
471473
* hash can enclose the bounding box then 0 is returned.
472474
*
473475
* @param topLeftLat
476+
* latitude of top left point (north west)
474477
* @param topLeftLon
478+
* longitude of top left point (north west)
475479
* @param bottomRightLat
480+
* latitude of bottom right point (south east)
476481
* @param bottomRightLon
477-
* @return
482+
* longitude of bottom right point (south east)
483+
* @return length of the hash
478484
*/
479485
public static int hashLengthToCoverBoundingBox(double topLeftLat, double topLeftLon,
480486
double bottomRightLat, double bottomRightLon) {
@@ -517,9 +523,12 @@ public static int hashLengthToCoverBoundingBox(double topLeftLat, double topLeft
517523
* contains the given lat and long.
518524
*
519525
* @param hash
526+
* hash to test containment in
520527
* @param lat
528+
* latitude
521529
* @param lon
522-
* @return
530+
* longitude
531+
* @return true if and only if the hash contains the given lat and long
523532
*/
524533
public static boolean hashContains(String hash, double lat, double lon) {
525534
LatLong centre = decodeHash(hash);
@@ -532,10 +541,14 @@ public static boolean hashContains(String hash, double lat, double lon) {
532541
* {@link GeoHash}.DEFAULT_MAX_HASHES.
533542
*
534543
* @param topLeftLat
544+
* latitude of top left point (north west)
535545
* @param topLeftLon
546+
* longitude of top left point (north west)
536547
* @param bottomRightLat
548+
* latitude of bottom right point (south east)
537549
* @param bottomRightLon
538-
* @return
550+
* longitude of bottom right point (south east)
551+
* @return coverage
539552
*/
540553
public static Coverage coverBoundingBox(double topLeftLat, final double topLeftLon,
541554
final double bottomRightLat, final double bottomRightLon) {
@@ -552,11 +565,16 @@ public static Coverage coverBoundingBox(double topLeftLat, final double topLeftL
552565
* will be {@link GeoHash}.MAX_HASH_LENGTH.
553566
*
554567
* @param topLeftLat
568+
* latitude of top left point (north west)
555569
* @param topLeftLon
570+
* longitude of top left point (north west)
556571
* @param bottomRightLat
572+
* latitude of bottom right point (south east)
557573
* @param bottomRightLon
574+
* longitude of bottom right point (south east)
558575
* @param maxHashes
559-
* @return
576+
* maximum number of hashes to use to cover the box
577+
* @return coverage
560578
*/
561579
public static Coverage coverBoundingBoxMaxHashes(double topLeftLat, final double topLeftLon,
562580
final double bottomRightLat, final double bottomRightLon, int maxHashes) {
@@ -582,11 +600,17 @@ public static Coverage coverBoundingBoxMaxHashes(double topLeftLat, final double
582600
* bounding box.
583601
*
584602
* @param topLeftLat
603+
* latitude of top left point (north west)
585604
* @param topLeftLon
605+
* longitude of top left point (north west)
586606
* @param bottomRightLat
607+
* latitude of bottom right point (south east)
587608
* @param bottomRightLon
609+
* longitude of bottom right point (south east)
588610
* @param length
589-
* @return
611+
* of hash
612+
* @return number of hashes of given length required to cover the given
613+
* bounding box
590614
*/
591615
public static Coverage coverBoundingBox(double topLeftLat, final double topLeftLon,
592616
final double bottomRightLat, final double bottomRightLon, final int length) {
@@ -649,11 +673,12 @@ static CoverageLongs coverBoundingBoxLongs(double topLeftLat, final double topLe
649673
}
650674

651675
/**
652-
* Returns height in degrees of all geohashes of length n. Results are
676+
* Returns height in degrees of all geohashes of length {@code n}. Results are
653677
* deterministic and cached to increase performance.
654678
*
655679
* @param n
656-
* @return
680+
* length of geohash
681+
* @return height in degrees of the geohash with length {@code n}
657682
*/
658683
public static double heightDegrees(int n) {
659684
if (n > MAX_HASH_LENGTH)
@@ -677,10 +702,10 @@ private static double[] createValues() {
677702

678703
/**
679704
* Returns the height in degrees of the region represented by a geohash of
680-
* length n.
705+
* length {@code n}.
681706
*
682-
* @param n
683-
* @return
707+
* @param n length of hash
708+
* @return height in degrees of the region represented by a geohash of length {@code n}
684709
*/
685710
private static double calculateHeightDegrees(int n) {
686711
double a;
@@ -710,8 +735,8 @@ private static double[] createValues() {
710735
* deterministic and cached to increase performance (might be unnecessary,
711736
* have not benchmarked).
712737
*
713-
* @param n
714-
* @return
738+
* @param n length of hash
739+
* @return width in degrees
715740
*/
716741
public static double widthDegrees(int n) {
717742
if (n > MAX_HASH_LENGTH)
@@ -724,8 +749,8 @@ public static double widthDegrees(int n) {
724749
* Returns the width in degrees of the region represented by a geohash of
725750
* length n.
726751
*
727-
* @param n
728-
* @return
752+
* @param n length of geohash
753+
* @return width in degrees
729754
*/
730755
private static double calculateWidthDegrees(int n) {
731756
double a;
@@ -742,7 +767,7 @@ private static double calculateWidthDegrees(int n) {
742767
* Returns a String of lines of hashes to represent the relative positions
743768
* of hashes on a map. The grid is of height and width 2*size centred around
744769
* the given hash. Highlighted hashes are displayed in upper case. For
745-
* example, gridToString("dr",1,Collections.<String>emptySet()) returns:
770+
* example, gridToString("dr",1,Collections.&lt;String&gt;emptySet()) returns:
746771
* </p>
747772
*
748773
* <pre>
@@ -751,10 +776,10 @@ private static double calculateWidthDegrees(int n) {
751776
* dn dq dw
752777
* </pre>
753778
*
754-
* @param hash
755-
* @param size
756-
* @param highlightThese
757-
* @return
779+
* @param hash central hash
780+
* @param size size of square grid in hashes
781+
* @param highlightThese hashes to highlight
782+
* @return String representation of grid
758783
*/
759784
public static String gridAsString(String hash, int size, Set<String> highlightThese) {
760785
return gridAsString(hash, -size, -size, size, size, highlightThese);
@@ -764,7 +789,7 @@ public static String gridAsString(String hash, int size, Set<String> highlightTh
764789
* Returns a String of lines of hashes to represent the relative positions
765790
* of hashes on a map.
766791
*
767-
* @param hash
792+
* @param hash reference hash
768793
* @param fromRight
769794
* top left of the grid in hashes to the right (can be negative).
770795
* @param fromBottom
@@ -776,7 +801,7 @@ public static String gridAsString(String hash, int size, Set<String> highlightTh
776801
* @param toBottom
777802
* bottom right of the grid in hashes to the bottom (can be
778803
* negative).
779-
* @return
804+
* @return string representation of grid
780805
*/
781806
public static String gridAsString(String hash, int fromRight, int fromBottom, int toRight,
782807
int toBottom) {
@@ -785,7 +810,7 @@ public static String gridAsString(String hash, int fromRight, int fromBottom, in
785810
}
786811

787812
/**
788-
* Returns a String of lines of hashes to represent the relative positions
813+
* <p>Returns a String of lines of hashes to represent the relative positions
789814
* of hashes on a map. Highlighted hashes are displayed in upper case. For
790815
* example, gridToString("dr",-1,-1,1,1,Sets.newHashSet("f2","f8")) returns:
791816
* </p>
@@ -796,7 +821,7 @@ public static String gridAsString(String hash, int fromRight, int fromBottom, in
796821
* dn dq dw
797822
* </pre>
798823
*
799-
* @param hash
824+
* @param hash reference hash
800825
* @param fromRight
801826
* top left of the grid in hashes to the right (can be negative).
802827
* @param fromBottom
@@ -808,8 +833,8 @@ public static String gridAsString(String hash, int fromRight, int fromBottom, in
808833
* @param toBottom
809834
* bottom right of the grid in hashes to the bottom (can be
810835
* negative).
811-
* @param highlightThese
812-
* @return
836+
* @param highlightThese hashes to highlight
837+
* @return String representation of grid
813838
*/
814839
public static String gridAsString(String hash, int fromRight, int fromBottom, int toRight,
815840
int toBottom, Set<String> highlightThese) {

‎src/main/java/com/github/davidmoten/geo/LatLong.java

+7-10
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@
33
/**
44
* A lat, long pair (WGS84). Immutable.
55
*
6-
* @author dave
7-
*
86
*/
97
public class LatLong {
108

@@ -14,19 +12,18 @@ public class LatLong {
1412
/**
1513
* Constructor.
1614
*
17-
* @param lat
18-
* @param lon
15+
* @param lat latitude in decimal degrees
16+
* @param lon longitude in decimal degrees
1917
*/
2018
public LatLong(double lat, double lon) {
21-
super();
2219
this.lat = lat;
2320
this.lon = lon;
2421
}
2522

2623
/**
2724
* Returns the latitude in decimal degrees.
2825
*
29-
* @return
26+
* @return latitude in decimal degrees
3027
*/
3128
public double getLat() {
3229
return lat;
@@ -35,7 +32,7 @@ public double getLat() {
3532
/**
3633
* Returns the longitude in decimal degrees.
3734
*
38-
* @return
35+
* @return longitude in decimal degrees
3936
*/
4037
public double getLon() {
4138
return lon;
@@ -45,9 +42,9 @@ public double getLon() {
4542
* Returns a new {@link LatLong} object with lat, lon increased by deltaLat,
4643
* deltaLon.
4744
*
48-
* @param deltaLat
49-
* @param deltaLon
50-
* @return
45+
* @param deltaLat change in latitude
46+
* @param deltaLon change in longitude
47+
* @return latitude and longitude
5148
*/
5249
public LatLong add(double deltaLat, double deltaLon) {
5350
return new LatLong(lat + deltaLat, lon + deltaLon);

0 commit comments

Comments
 (0)