Improve API-docs

Author: chrismayer

src/main/java/de/meggsimum/w3w/Coordinates.java

@@ -1,21 +1,47 @@
 package de.meggsimum.w3w;
 
+/**
+ * Class represents a position object holding its coordinates (lat/lon).
+ */
 public class Coordinates {
+    
+    /** latitude of this coordinate */
     private double latitude;
+    
+    /** longitude of this coordinate */
     private double longitude;
 
+    /**
+     * Creates an empty {@linkplain Coordinates} object
+     * 
+     * @param latitude
+     * @param longitude
+     */
     public Coordinates() {
     }
 
+    /**
+     * Creates a {@linkplain Coordinates} object with the given latitude and
+     * longitude
+     * 
+     * @param latitude
+     * @param longitude
+     */
     public Coordinates(double latitude, double longitude) {
         this.latitude = latitude;
         this.longitude = longitude;
     }
 
+    /**
+     * @return latitude
+     */
     public double getLatitude() {
         return latitude;
     }
 
+    /**
+     * @return longitude
+     */
     public double getLongitude() {
         return longitude;
     }

src/main/java/de/meggsimum/w3w/ThreeWords.java

@@ -1,39 +1,76 @@
 package de.meggsimum.w3w;
 
+/**
+ * Class represents a "w3w-address" object holding the corresponding three
+ * words.
+ */
 public class ThreeWords {
+    
+    /** the first word of this "w3w-address" */
     private String first;
+    
+    /** the first word of this "w3w-address" */
     private String second;
+    
+    /** the first word of this "w3w-address" */
     private String third;
 
+    /**
+     * Creates an empty {@linkplain ThreeWords} object.
+     */
     public ThreeWords() {
     }
 
+    /**
+     * Creates a {@linkplain ThreeWords} object with the given three words.
+     */
     public ThreeWords(String first, String second, String third) {
         this.first = first;
         this.second = second;
         this.third = third;
     }
 
+    /**
+     * @return first word of this "w3w-address"
+     */
     public String getFirst() {
         return first;
     }
 
+    /**
+     * @param first
+     *            the first word of this "w3w-address" to set
+     */
     public void setFirst(String first) {
         this.first = first;
     }
 
+    /**
+     * @return second word of this "w3w-address"
+     */
     public String getSecond() {
         return second;
     }
 
+    /**
+     * @param second
+     *            the second word of this "w3w-address" to set
+     */
     public void setSecond(String second) {
         this.second = second;
     }
 
+    /**
+     * @return third word of this "w3w-address"
+     */
     public String getThird() {
         return third;
     }
 
+    /**
+     * @param third
+     *            the third word of this "w3w-address" to set
+     */
     public void setThird(String third) {
         this.third = third;
     }

src/main/java/de/meggsimum/w3w/What3Words.java

@@ -50,18 +50,41 @@ public What3Words(String apiKey) {
 	 * given language.
 	 *
 	 * @param apiKey
-	 * @param language default Language
+	 * @param language
+	 *            default Language
 	 */
 	public What3Words(String apiKey, String language) {
 		this.apiKey = apiKey;
 		this.language = language;
 	}
 
+	/**
+	 * Converts 3 words object (in the given language) into a position object.
+	 * 
+	 * @param threeWords
+	 *            "w3w-address" object in the given language
+	 * @param language
+	 *            string defining the language of the words (e.g. "de")
+	 * @return coordinates object holding the coordinates reprsenting the given
+	 *         words
+	 * @throws IOException
+	 * @throws What3WordsException
+	 */
 	public Coordinates wordsToPosition(ThreeWords threeWords, String language) throws IOException, What3WordsException {
 		double[] doubleCoordinates = wordsToPosition(new String[]{threeWords.getFirst(), threeWords.getSecond(), threeWords.getThird()});
 		return new Coordinates(doubleCoordinates[0], doubleCoordinates[1]);
 	}
 
+	/**
+	 * Converts 3 words object into a position object.
+	 * 
+	 * @param threeWords
+	 *            "w3w-address" object in the given language
+	 * @return coordinates object holding the coordinates reprsenting the given
+	 *         words
+	 * @throws IOException
+	 * @throws What3WordsException
+	 */
 	public Coordinates wordsToPosition(ThreeWords threeWords) throws IOException, What3WordsException {
 		return wordsToPosition(threeWords, this.language);
 	}
@@ -123,11 +146,30 @@ public double[] wordsToPosition(String[] words, String language) throws IOExcept
 
 	}
 
+	/**
+	 * Converts a position object into a "w3w-address" object (in the given
+	 * language)
+	 * 
+	 * @param position object holding the coordinates to be transformed
+	 * @param language string defining the language of the words (e.g. "de") 
+	 * @return "w3w-address" object in the given language
+	 * @throws IOException
+	 * @throws What3WordsException
+	 */
 	public ThreeWords positionToWords(Coordinates coordinates, String language) throws IOException, What3WordsException {
 		String[] words = positionToWords(new double[]{coordinates.getLatitude(), coordinates.getLongitude()}, language);
 		return new ThreeWords(words[0], words[1], words[2]);
 	}
 
+	/**
+	 * Converts a position object into a "w3w-address" object with default
+	 * language.
+	 * 
+	 * @param position object holding the coordinates to be transformed
+	 * @return "w3w-address" object
+	 * @throws IOException
+	 * @throws What3WordsException
+	 */
 	public ThreeWords positionToWords(Coordinates coordinates) throws IOException, What3WordsException {
 		return positionToWords(coordinates, this.language);
 	}