Merge pull request #321 from apjanke/google-style-javadoc_P

Javadoc: Rephrase to match Google Java Style Guide (classes P)

src/main/java/com/google/maps/PendingResult.java

@@ -19,22 +19,24 @@
 import java.io.IOException;
 
 /**
- * Represents a pending result from an API call.
+ * A pending result from an API call.
  *
  * @param <T> the type of the result object.
  */
 public interface PendingResult<T> {
 
   /**
-   * Performs the request asynchronously, calling onResult or onFailure after the request has been
+   * Performs the request asynchronously, calling {@link
+   * com.google.maps.PendingResult.Callback#onResult onResult} or {@link
+   * com.google.maps.PendingResult.Callback#onFailure onFailure} after the request has been
    * completed.
    *
    * @param callback The callback to call on completion.
    */
   void setCallback(Callback<T> callback);
 
   /**
-   * Performs the GET request synchronously.
+   * Performs the request synchronously.
    *
    * @return The result.
    * @throws ApiException Thrown if the API Returned result is an error.
@@ -52,10 +54,14 @@ public interface PendingResult<T> {
    */
   T awaitIgnoreError();
 
-  /** Attempt to cancel the request. */
+  /** Attempts to cancel the request. */
   void cancel();
 
-  /** The callback interface the API client code needs to implement to handle API results. */
+  /**
+   * The callback interface the API client code needs to implement to handle API results.
+   *
+   * @param <T> The type of the result object.
+   */
   interface Callback<T> {
 
     /**

src/main/java/com/google/maps/PhotoRequest.java

@@ -44,7 +44,7 @@ protected void validateRequest() {
   }
 
   /**
-   * Set the photoReference for this request.
+   * Sets the photoReference for this request.
    *
    * @param photoReference A string identifier that uniquely identifies a photo. Photo references
    *     are returned from either a Place Search or Place Details request.
@@ -55,21 +55,21 @@ public PhotoRequest photoReference(String photoReference) {
   }
 
   /**
-   * Set the maxHeight for this request.
+   * Sets the maxHeight for this request.
    *
-   * @param maxHeight Specifies the maximum desired height, in pixels, of the image returned by the
-   *     Place Photos service.
+   * @param maxHeight The maximum desired height, in pixels, of the image returned by the Place
+   *     Photos service.
    * @return Returns the configured PhotoRequest.
    */
   public PhotoRequest maxHeight(int maxHeight) {
     return param("maxheight", String.valueOf(maxHeight));
   }
 
   /**
-   * Set the maxWidth for this request.
+   * Sets the maxWidth for this request.
    *
-   * @param maxWidth Specifies the maximum desired width, in pixels, of the image returned by the
-   *     Place Photos service.
+   * @param maxWidth The maximum desired width, in pixels, of the image returned by the Place Photos
+   *     service.
    * @return Returns the configured PhotoRequest.
    */
   public PhotoRequest maxWidth(int maxWidth) {

src/main/java/com/google/maps/PlaceAutocompleteRequest.java

@@ -44,8 +44,8 @@ protected PlaceAutocompleteRequest(GeoApiContext context) {
   }
 
   /**
-   * input is the text string on which to search. The Places service will return candidate matches
-   * based on this string and order results based on their perceived relevance.
+   * Sets the text string on which to search. The Places service will return candidate matches based
+   * on this string and order results based on their perceived relevance.
    *
    * @param input The input text to autocomplete.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.
@@ -55,10 +55,10 @@ public PlaceAutocompleteRequest input(String input) {
   }
 
   /**
-   * offset is the character position in the input term at which the service uses text for
-   * predictions. For example, if the input is 'Googl' and the completion point is 3, the service
-   * will match on 'Goo'. The offset should generally be set to the position of the text caret. If
-   * no offset is supplied, the service will use the entire term.
+   * The character position in the input term at which the service uses text for predictions. For
+   * example, if the input is 'Googl' and the completion point is 3, the service will match on
+   * 'Goo'. The offset should generally be set to the position of the text caret. If no offset is
+   * supplied, the service will use the entire term.
    *
    * @param offset The character offset position of the user's cursor.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.
@@ -68,7 +68,7 @@ public PlaceAutocompleteRequest offset(int offset) {
   }
 
   /**
-   * location is the point around which you wish to retrieve place information.
+   * The point around which you wish to retrieve place information.
    *
    * @param location The {@link LatLng} location to center this autocomplete search.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.
@@ -78,9 +78,8 @@ public PlaceAutocompleteRequest location(LatLng location) {
   }
 
   /**
-   * radius is the distance (in meters) within which to return place results. Note that setting a
-   * radius biases results to the indicated area, but may not fully restrict results to the
-   * specified area.
+   * The distance (in meters) within which to return place results. Note that setting a radius
+   * biases results to the indicated area, but may not fully restrict results to the specified area.
    *
    * @param radius The radius over which to bias results.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.
@@ -90,7 +89,7 @@ public PlaceAutocompleteRequest radius(int radius) {
   }
 
   /**
-   * type restricts the results to places matching the specified type.
+   * Restricts the results to places matching the specified type.
    *
    * @param type The type to restrict results to.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.
@@ -100,8 +99,8 @@ public PlaceAutocompleteRequest type(PlaceAutocompleteType type) {
   }
 
   /**
-   * Components is a grouping of places to which you would like to restrict your results. Currently,
-   * you can use components to filter by country.
+   * A grouping of places to which you would like to restrict your results. Currently, you can use
+   * components to filter by country.
    *
    * @param filters The component filter to restrict results with.
    * @return Returns this {@code PlaceAutocompleteRequest} for call chaining.

src/main/java/com/google/maps/PlaceDetailsRequest.java

@@ -37,7 +37,7 @@ public PlaceDetailsRequest(GeoApiContext context) {
   }
 
   /**
-   * Get the Place Details for the specified Place ID. Required.
+   * Specifies the Place ID to get Place Details for. Required.
    *
    * @param placeId The Place ID to retrieve details for.
    * @return Returns this {@code PlaceDetailsRequest} for call chaining.

src/main/java/com/google/maps/PlacesApi.java

@@ -31,7 +31,7 @@ public class PlacesApi {
   private PlacesApi() {}
 
   /**
-   * Perform a search for nearby Places.
+   * Performs a search for nearby Places.
    *
    * @param context The context on which to make Geo API requests.
    * @param location The latitude/longitude around which to retrieve place information.
@@ -44,7 +44,7 @@ public static NearbySearchRequest nearbySearchQuery(GeoApiContext context, LatLn
   }
 
   /**
-   * Retrieve the next page of Nearby Search results. The nextPageToken, returned in a
+   * Retrieves the next page of Nearby Search results. The nextPageToken, returned in a
    * PlacesSearchResponse when there are more pages of results, encodes all of the original Nearby
    * Search Request parameters, which are thus not required on this call.
    *
@@ -60,7 +60,7 @@ public static NearbySearchRequest nearbySearchNextPage(
   }
 
   /**
-   * Perform a search for Places using a text query; for example, "pizza in New York" or "shoe
+   * Performs a search for Places using a text query; for example, "pizza in New York" or "shoe
    * stores near Ottawa".
    *
    * @param context The context on which to make Geo API requests.
@@ -74,7 +74,7 @@ public static TextSearchRequest textSearchQuery(GeoApiContext context, String qu
   }
 
   /**
-   * Retrieve the next page of Text Search results. The nextPageToken, returned in a
+   * Retrieves the next page of Text Search results. The nextPageToken, returned in a
    * PlacesSearchResponse when there are more pages of results, encodes all of the original Text
    * Search Request parameters, which are thus not required on this call.
    *
@@ -89,7 +89,7 @@ public static TextSearchRequest textSearchNextPage(GeoApiContext context, String
   }
 
   /**
-   * Perform a radar search for up to 200 places, but with less detail than is returned from Text
+   * Performs a radar search for up to 200 places, but with less detail than is returned from Text
    * Search or Nearby Search.
    *
    * @deprecated This functionality is deprecated and will stop working on June 30, 2018.
@@ -110,7 +110,7 @@ public static RadarSearchRequest radarSearchQuery(
   }
 
   /**
-   * Request the details of a Place.
+   * Requests the details of a Place.
    *
    * <p>We are only enabling looking up Places by placeId as the older Place identifier, reference,
    * is deprecated. Please see the <a
@@ -128,7 +128,7 @@ public static PlaceDetailsRequest placeDetails(GeoApiContext context, String pla
   }
 
   /**
-   * Request a Photo from a PhotoReference.
+   * Requests a Photo from a PhotoReference.
    *
    * <p>Note: If you want to use a Photo in a web browser, please retrieve the photos for a place
    * via our <a
@@ -148,8 +148,9 @@ public static PhotoRequest photo(GeoApiContext context, String photoReference) {
   }
 
   /**
-   * The Place Autocomplete service can match on full words as well as substrings. Applications can
-   * therefore send queries as the user types, to provide on-the-fly place predictions.
+   * Creates a new Places Autocomplete request for a given input. The Place Autocomplete service can
+   * match on full words as well as substrings. Applications can therefore send queries as the user
+   * types, to provide on-the-fly place predictions.
    *
    * @param context The context on which to make Geo API requests.
    * @param input input is the text string on which to search.
@@ -162,8 +163,7 @@ public static PlaceAutocompleteRequest placeAutocomplete(GeoApiContext context,
   }
 
   /**
-   * Query Autocomplete allows you to add on-the-fly geographic query predictions to your
-   * application.
+   * Allows you to add on-the-fly geographic query predictions to your application.
    *
    * @param context The context on which to make Geo API requests.
    * @param input input is the text string on which to search.

src/main/java/com/google/maps/model/Photo.java

@@ -16,21 +16,21 @@
 package com.google.maps.model;
 
 /**
- * This describes a photo available with a Search Result.
+ * Describes a photo available with a Search Result.
  *
  * <p>Please see <a href="https://developers.google.com/places/web-service/photos">Place Photos</a>
  * for more details.
  */
 public class Photo {
-  /** photoReference is used to identify the photo when you perform a Photo request. */
+  /** Used to identify the photo when you perform a Photo request. */
   public String photoReference;
 
-  /** height is the maximum height of the image. */
+  /** The maximum height of the image. */
   public int height;
 
-  /** width is the maximum width of the image. */
+  /** The maximum width of the image. */
   public int width;
 
-  /** htmlAttributions contains any required attributions. */
+  /** Attributions about this listing which must be displayed to the user. */
   public String[] htmlAttributions;
 }

src/main/java/com/google/maps/model/PhotoResult.java

@@ -16,15 +16,15 @@
 package com.google.maps.model;
 
 /**
- * PhotoResult contains the photo for a PhotoReference.
+ * Contains the photo for a PhotoReference.
  *
  * <p>Please see <a href="https://developers.google.com/places/web-service/photos">Place Photos</a>
  * for more details.
  */
 public class PhotoResult {
-  /** imageData is the byte array of returned image data from the Photos API call. */
+  /** The image data from the Photos API call. */
   public byte[] imageData;
 
-  /** contentType is the Content-Type header of the returned result. */
+  /** The Content-Type header of the returned result. */
   public String contentType;
 }

src/main/java/com/google/maps/model/PlaceAutocompleteType.java

@@ -18,8 +18,8 @@
 import com.google.maps.internal.StringJoin;
 
 /**
- * PlaceAutocompleteType is used by the Places API to restrict the autocomplete results to places
- * matching the specified type.
+ * Used by the Places API to restrict the autocomplete results to places matching the specified
+ * type.
  */
 public enum PlaceAutocompleteType implements StringJoin.UrlValue {
   GEOCODE("geocode"),