From c15430cdedde6ea066a400b18ccd29f22adbae5f Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Thu, 10 Aug 2017 01:19:51 -0400 Subject: [PATCH] Javadoc: Rephrase to match Google Java Style Guide (classes P) This rephrases several Javadoc elements to conform with section 7 of the Google Java Style Guide. --- .../java/com/google/maps/PendingResult.java | 16 ++- .../java/com/google/maps/PhotoRequest.java | 14 +-- .../google/maps/PlaceAutocompleteRequest.java | 25 ++--- .../com/google/maps/PlaceDetailsRequest.java | 2 +- src/main/java/com/google/maps/PlacesApi.java | 22 ++-- .../java/com/google/maps/model/Photo.java | 10 +- .../com/google/maps/model/PhotoResult.java | 6 +- .../maps/model/PlaceAutocompleteType.java | 4 +- .../com/google/maps/model/PlaceDetails.java | 104 +++++++++--------- .../com/google/maps/model/PlaceIdScope.java | 8 +- .../java/com/google/maps/model/PlaceType.java | 5 +- .../maps/model/PlacesSearchResponse.java | 10 +- .../google/maps/model/PlacesSearchResult.java | 32 +++--- .../com/google/maps/model/PriceLevel.java | 2 +- 14 files changed, 125 insertions(+), 135 deletions(-) diff --git a/src/main/java/com/google/maps/PendingResult.java b/src/main/java/com/google/maps/PendingResult.java index 0206c52c2..1c9acc285 100644 --- a/src/main/java/com/google/maps/PendingResult.java +++ b/src/main/java/com/google/maps/PendingResult.java @@ -19,14 +19,16 @@ import java.io.IOException; /** - * Represents a pending result from an API call. + * A pending result from an API call. * * @param the type of the result object. */ public interface PendingResult { /** - * 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. @@ -34,7 +36,7 @@ public interface PendingResult { void setCallback(Callback 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 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 The type of the result object. + */ interface Callback { /** diff --git a/src/main/java/com/google/maps/PhotoRequest.java b/src/main/java/com/google/maps/PhotoRequest.java index 06e04b64a..84594a3f0 100644 --- a/src/main/java/com/google/maps/PhotoRequest.java +++ b/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,10 +55,10 @@ 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) { @@ -66,10 +66,10 @@ public PhotoRequest maxHeight(int 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) { diff --git a/src/main/java/com/google/maps/PlaceAutocompleteRequest.java b/src/main/java/com/google/maps/PlaceAutocompleteRequest.java index 0a3c1e6c4..034b35e88 100644 --- a/src/main/java/com/google/maps/PlaceAutocompleteRequest.java +++ b/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. diff --git a/src/main/java/com/google/maps/PlaceDetailsRequest.java b/src/main/java/com/google/maps/PlaceDetailsRequest.java index 714fe4eee..267d445ca 100644 --- a/src/main/java/com/google/maps/PlaceDetailsRequest.java +++ b/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. diff --git a/src/main/java/com/google/maps/PlacesApi.java b/src/main/java/com/google/maps/PlacesApi.java index 8e813437f..fd828e4ba 100644 --- a/src/main/java/com/google/maps/PlacesApi.java +++ b/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. * *

We are only enabling looking up Places by placeId as the older Place identifier, reference, * is deprecated. Please see the Note: If you want to use a Photo in a web browser, please retrieve the photos for a place * via our Please see Place Photos * 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; } diff --git a/src/main/java/com/google/maps/model/PhotoResult.java b/src/main/java/com/google/maps/model/PhotoResult.java index 01c83e464..249b71bd3 100644 --- a/src/main/java/com/google/maps/model/PhotoResult.java +++ b/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. * *

Please see Place Photos * 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; } diff --git a/src/main/java/com/google/maps/model/PlaceAutocompleteType.java b/src/main/java/com/google/maps/model/PlaceAutocompleteType.java index 9bcf215ff..75b87b649 100644 --- a/src/main/java/com/google/maps/model/PlaceAutocompleteType.java +++ b/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"), diff --git a/src/main/java/com/google/maps/model/PlaceDetails.java b/src/main/java/com/google/maps/model/PlaceDetails.java index 89d13df3f..d845357c9 100644 --- a/src/main/java/com/google/maps/model/PlaceDetails.java +++ b/src/main/java/com/google/maps/model/PlaceDetails.java @@ -19,52 +19,52 @@ import org.joda.time.Instant; /** - * PlaceDetails is the result of a Place Details request. A Place Details request returns more - * comprehensive information about the indicated place such as its complete address, phone number, - * user rating, and reviews. + * The result of a Place Details request. A Place Details request returns more comprehensive + * information about the indicated place such as its complete address, phone number, user rating, and + * reviews. * *

See * Place Details Results for more detail. */ public class PlaceDetails { - /** addressComponents is a list of separate address components used to compose a given address. */ + /** A list of separate address components that comprise the address of this place. */ public AddressComponent[] addressComponents; - /** formattedAddress is a string containing the human-readable address of this place. */ + /** The human-readable address of this place. */ public String formattedAddress; - /** formattedPhoneNumber contains the place's phone number in its local format. */ + /** The place's phone number in its local format. */ public String formattedPhoneNumber; - /** geometry is the location of the Place. */ + /** The location of the Place. */ public Geometry geometry; /** - * icon contains the URL of a suggested icon which may be displayed to the user when indicating - * this result on a map. + * The URL of a suggested icon which may be displayed to the user when indicating this result on a + * map. */ public URL icon; /** - * internationalPhoneNumber contains the place's phone number in international format. - * International format includes the country code, and is prefixed with the plus (+) sign. + * The place's phone number in international format. International format includes the country + * code, and is prefixed with the plus (+) sign. */ public String internationalPhoneNumber; - /** name contains the human-readable name for the returned result. */ + /** The human-readable name for the returned result. */ public String name; /** The opening hours for the place. */ public OpeningHours openingHours; - /** photos is a list of photo objects, each containing a reference to an image. */ + /** A list of photos associated with this place, each containing a reference to an image. */ public Photo[] photos; - /** placeId is a textual identifier that uniquely identifies a place. */ + /** A textual identifier that uniquely identifies this place. */ public String placeId; - /** scope: Indicates the scope of the placeId. */ + /** The scope of the placeId. */ public PlaceIdScope scope; /** Whether the place has permanently closed. */ @@ -72,32 +72,32 @@ public class PlaceDetails { public static class AlternatePlaceIds { /** - * placeId — The most likely reason for a place to have an alternative place ID is if your - * application adds a place and receives an application-scoped place ID, then later receives a - * Google-scoped place ID after passing the moderation process. + * The alternative placeId. The most likely reason for a place to have an alternative place ID + * is if your application adds a place and receives an application-scoped place ID, then later + * receives a Google-scoped place ID after passing the moderation process. */ public String placeId; /** - * scope — The scope of an alternative place ID will always be APP, indicating that the - * alternative place ID is recognised by your application only. + * The scope of an alternative place ID will always be APP, indicating that the alternative + * place ID is recognised by your application only. */ public PlaceIdScope scope; } /** - * altIds is an optional array of alternative place IDs for the place, with a scope related to - * each alternative ID. + * An optional array of alternative place IDs for the place, with a scope related to each + * alternative ID. */ public AlternatePlaceIds[] altIds; /** - * priceLevel is the price level of the place. The exact amount indicated by a specific value will - * vary from region to region. + * The price level of the place. The exact amount indicated by a specific value will vary from + * region to region. */ public PriceLevel priceLevel; - /** rating contains the place's rating, from 1.0 to 5.0, based on aggregated user reviews. */ + /** The place's rating, from 1.0 to 5.0, based on aggregated user reviews. */ public float rating; public static class Review { @@ -119,16 +119,16 @@ public enum RatingType { UNKNOWN } - /** type is the name of the aspect that is being rated. */ + /** The name of the aspect that is being rated. */ public RatingType type; - /** rating is the user's rating for this particular aspect, from 0 to 3. */ + /** The user's rating for this particular aspect, from 0 to 3. */ public int rating; } /** - * aspects contains a collection of AspectRating objects, each of which provides a rating of a - * single attribute of the establishment. + * A list of AspectRating objects, each of which provides a rating of a single attribute of the + * establishment. * *

Note: this is a Premium Data @@ -137,65 +137,59 @@ public enum RatingType { public AspectRating[] aspects; /** - * authorName the name of the user who submitted the review. Anonymous reviews are attributed to - * "A Google user". + * The name of the user who submitted the review. Anonymous reviews are attributed to "A Google + * user". */ public String authorName; - /** authorUrl the URL to the user's Google+ profile, if available. */ + /** The URL of the user's Google+ profile, if available. */ public URL authorUrl; - /** language an IETF language code indicating the language used in the user's review. */ + /** An IETF language code indicating the language used in the user's review. */ public String language; - /** - * rating the user's overall rating for this place. This is a whole number, ranging from 1 to 5. - */ + /** The user's overall rating for this place. This is a whole number, ranging from 1 to 5. */ public int rating; /** - * text is the user's review. When reviewing a location with Google Places, text reviews are - * considered optional. + * The user's review. When reviewing a location with Google Places, text reviews are considered + * optional. */ public String text; - /** time is the time that the review was submitted, as seconds since epoch. */ + /** The time that the review was submitted. */ public Instant time; } /** - * reviews is an array of up to five reviews. If a language parameter was specified in the Place - * Details request, the Places Service will bias the results to prefer reviews written in that - * language. + * An array of up to five reviews. If a language parameter was specified in the Place Details + * request, the Places Service will bias the results to prefer reviews written in that language. */ public Review[] reviews; - /** types contains an array of feature types describing the given result. */ + /** Feature types describing the given result. */ public String[] types; /** - * url contains the URL of the official Google page for this place. This will be the - * establishment's Google+ page if the Google+ page exists, otherwise it will be the Google-owned - * page that contains the best available information about the place. Applications must link to or - * embed this page on any screen that shows detailed results about the place to the user. + * The URL of the official Google page for this place. This will be the establishment's Google+ + * page if the Google+ page exists, otherwise it will be the Google-owned page that contains the + * best available information about the place. Applications must link to or embed this page on any + * screen that shows detailed results about the place to the user. */ public URL url; - /** utcOffset contains the number of minutes this place’s current timezone is offset from UTC. */ + /** The number of minutes this place’s current timezone is offset from UTC. */ public int utcOffset; /** - * vicinity lists a simplified address for the place, including the street name, street number, - * and locality, but not the province/state, postal code, or country. + * A simplified address for the place, including the street name, street number, and locality, but + * not the province/state, postal code, or country. */ public String vicinity; - /** website lists the authoritative website for this place, such as a business's homepage. */ + /** The authoritative website for this place, such as a business's homepage. */ public URL website; - /** - * htmlAttributions contains an array of attributions about this listing which must be displayed - * to the user. - */ + /** Attributions about this listing which must be displayed to the user. */ public String[] htmlAttributions; } diff --git a/src/main/java/com/google/maps/model/PlaceIdScope.java b/src/main/java/com/google/maps/model/PlaceIdScope.java index 9c64ae757..a93f177a2 100644 --- a/src/main/java/com/google/maps/model/PlaceIdScope.java +++ b/src/main/java/com/google/maps/model/PlaceIdScope.java @@ -15,13 +15,13 @@ package com.google.maps.model; -/** Place ID scope is the scope of a Place ID returned from the Google Places API Web Service. */ +/** The scope of a Place ID returned from the Google Places API Web Service. */ public enum PlaceIdScope { /** - * APP indicates the place ID is recognised by your application only. This is because your - * application added the place, and the place has not yet passed the moderation process. + * Indicates the place ID is recognised by your application only. This is because your application + * added the place, and the place has not yet passed the moderation process. */ APP, - /** GOOGLE indicates the place ID is available to other applications and on Google Maps. */ + /** Indicates the place ID is available to other applications and on Google Maps. */ GOOGLE } diff --git a/src/main/java/com/google/maps/model/PlaceType.java b/src/main/java/com/google/maps/model/PlaceType.java index 3e894ec15..94154d165 100644 --- a/src/main/java/com/google/maps/model/PlaceType.java +++ b/src/main/java/com/google/maps/model/PlaceType.java @@ -17,10 +17,7 @@ import com.google.maps.internal.StringJoin; -/** - * PlaceType is used by the Places API to restrict the results to places matching the specified - * type. - */ +/** Used by the Places API to restrict the results to places matching the specified type. */ public enum PlaceType implements StringJoin.UrlValue { ACCOUNTING("accounting"), AIRPORT("airport"), diff --git a/src/main/java/com/google/maps/model/PlacesSearchResponse.java b/src/main/java/com/google/maps/model/PlacesSearchResponse.java index 9c7085b4f..3feecd0c6 100644 --- a/src/main/java/com/google/maps/model/PlacesSearchResponse.java +++ b/src/main/java/com/google/maps/model/PlacesSearchResponse.java @@ -27,16 +27,12 @@ public class PlacesSearchResponse { /** The list of Search Results. */ public PlacesSearchResult results[]; - /** - * htmlAttributions contain a set of attributions about this listing which must be displayed to - * the user. - */ + /** Attributions about this listing which must be displayed to the user. */ public String htmlAttributions[]; /** - * nextPageToken is a token that can be used to request up to 20 additional results. This field - * will be null if there are no further results. The maximum number of results that can be - * returned is 60. + * A token that can be used to request up to 20 additional results. This field will be null if + * there are no further results. The maximum number of results that can be returned is 60. * *

Note: There is a short delay between when this response is issued, and when nextPageToken * will become valid to execute. diff --git a/src/main/java/com/google/maps/model/PlacesSearchResult.java b/src/main/java/com/google/maps/model/PlacesSearchResult.java index 4a4457c17..3ff483c22 100644 --- a/src/main/java/com/google/maps/model/PlacesSearchResult.java +++ b/src/main/java/com/google/maps/model/PlacesSearchResult.java @@ -18,8 +18,7 @@ import java.net.URL; /** - * PlacesSearchResult represents a single result in the search results returned from the Google - * Places API Web Service. + * A single result in the search results returned from the Google Places API Web Service. * *

Please see Place Search @@ -27,48 +26,47 @@ */ public class PlacesSearchResult { - /** formattedAddress is a string containing the human-readable address of this place. */ + /** The human-readable address of this place. */ public String formattedAddress; /** - * geometry contains geometry information about the result, generally including the location - * (geocode) of the place and (optionally) the viewport identifying its general area of coverage. + * Geometry information about the result, generally including the location (geocode) of the place + * and (optionally) the viewport identifying its general area of coverage. */ public Geometry geometry; /** - * name contains the human-readable name for the returned result. For establishment results, this - * is usually the business name. + * The human-readable name for the returned result. For establishment results, this is usually the + * business name. */ public String name; /** - * icon contains the URL of a recommended icon which may be displayed to the user when indicating - * this result. + * The URL of a recommended icon which may be displayed to the user when indicating this result. */ public URL icon; - /** placeId is a textual identifier that uniquely identifies a place. */ + /** A textual identifier that uniquely identifies a place. */ public String placeId; - /** scope indicates the scope of the placeId. */ + /** sThe scope of the placeId. */ public PlaceIdScope scope; - /** rating contains the place's rating, from 1.0 to 5.0, based on aggregated user reviews. */ + /** The place's rating, from 1.0 to 5.0, based on aggregated user reviews. */ public float rating; - /** types contains an array of feature types describing the given result. */ + /** Feature types describing the given result. */ public String types[]; - /** openingHours may contain information on when the place is open. */ + /** Information on when the place is open. */ public OpeningHours openingHours; - /** photos is an array of photo objects, each containing a reference to an image. */ + /** Photo objects associated with this place, each containing a reference to an image. */ public Photo photos[]; - /** vicinity contains a feature name of a nearby location. */ + /** A feature name of a nearby location. */ public String vicinity; - /** permanentlyClosed is a boolean flag indicating whether the place has permanently shut down. */ + /** Indicates that the place has permanently shut down. */ public boolean permanentlyClosed; } diff --git a/src/main/java/com/google/maps/model/PriceLevel.java b/src/main/java/com/google/maps/model/PriceLevel.java index c802fb36d..1dc3571aa 100644 --- a/src/main/java/com/google/maps/model/PriceLevel.java +++ b/src/main/java/com/google/maps/model/PriceLevel.java @@ -17,7 +17,7 @@ import com.google.maps.internal.StringJoin; -/** PriceLevel is used by Places API to restrict search results to those within a price range. */ +/** Used by Places API to restrict search results to those within a given price range. */ public enum PriceLevel implements StringJoin.UrlValue { FREE("0"), INEXPENSIVE("1"),