From 9deaf93c7fb6d069c88352f9ac3ccc95e6ba1e1b Mon Sep 17 00:00:00 2001
From: Jason Hall <imjasonh@gmail.com>
Date: Mon, 13 Oct 2014 12:15:04 -0400
Subject: [PATCH] Add doc comments for Distance Matrix API methods

---
 distance.go | 65 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 55 insertions(+), 10 deletions(-)

diff --git a/distance.go b/distance.go
index a7dc626..8b9b0f6 100644
--- a/distance.go
+++ b/distance.go
@@ -6,6 +6,9 @@ import (
 	"time"
 )
 
+// DistanceMatrix requests travel distance and time for a matrix of origins and destinations.
+//
+// See https://developers.google.com/maps/documentation/distancematrix/
 func (c Client) DistanceMatrix(orig, dest []Location, opts *DistanceMatrixOpts) (*DistanceMatrixResult, error) {
 	var d distanceResponse
 	if err := c.doDecode(baseURL+distancematrix(orig, dest, opts), &d); err != nil {
@@ -25,24 +28,50 @@ func distancematrix(orig, dest []Location, opts *DistanceMatrixOpts) string {
 	return "distancematrix/json?" + p.Encode()
 }
 
+// DistanceMatrixOpts defines options for DistanceMatrix requsts.
 type DistanceMatrixOpts struct {
-	Language, Units string
-	Mode, Avoid     *string
-	DepartureTime   time.Time
+	// The language in which to return results.
+	//
+	// See https://developers.google.com/maps/faq#languagesupport
+	Language string
+
+	// Specifies the unit system to use when displaying results.
+	//
+	// Accepted values are UnitMetric and UnitImperial.
+	//
+	// See https://developers.google.com/maps/documentation/distancematrix/#unit_systems
+	Units string
+
+	// Specifies the mode of transport to use when calculating directions.
+	//
+	// Accepted values are ModeDriving (the default), ModeWalking and ModeBicycling.
+	Mode string
+
+	// Indicates that the calculated route(s) should avoid the indicated features.
+	//
+	// Accepted values are AvoidTolls, AvoidHighways or AvoidFerries
+	//
+	// See https://developers.google.com/maps/documentation/distancematrix/#Restrictions
+	Avoid string
+
+	// Specifies the desired time of departure.
+	//
+	// The departure time can be specified for Google Maps API for Work clients to receive trip duration considering current traffic conditions.
+	DepartureTime time.Time
 }
 
 func (o *DistanceMatrixOpts) update(p url.Values) {
 	if o == nil {
 		return
 	}
-	if o.Mode != nil {
-		p.Set("mode", *o.Mode)
+	if o.Mode != "" {
+		p.Set("mode", o.Mode)
 	}
 	if o.Language != "" {
 		p.Set("language", o.Language)
 	}
-	if o.Avoid != nil {
-		p.Set("avoid", *o.Avoid)
+	if o.Avoid != "" {
+		p.Set("avoid", o.Avoid)
 	}
 	if o.Units != "" {
 		p.Set("units", o.Units)
@@ -57,13 +86,29 @@ type distanceResponse struct {
 	DistanceMatrixResult
 }
 
+// DistanceMatrixResult describes the matrix of distances between the requested origins and destinations.
 type DistanceMatrixResult struct {
-	OriginAddresses      []string `json:"origin_addresses"`
+	// OriginAddresses contains the addresses returned by the API from your original request.
+	//
+	// These are formatted by the geocoder and localized according to the requested Language.
+	OriginAddresses []string `json:"origin_addresses"`
+
+	// DestinationAddresses contains the addresses returned by the API from your original request.
+	//
+	// These are formatted by the geocoder and localized according to the requested Language.
 	DestinationAddresses []string `json:"destination_addresses"`
-	Rows                 []struct {
+
+	// Rows describes rows in the matrix.
+	Rows []struct {
+		// Elements describes columns in the matrix.
 		Elements []struct {
-			Status   string   `json:"status"`
+			// Status indicates the status of the request, and will be one of StatusOK, StatusNotFound or StatusZeroResults.
+			Status string `json:"status"`
+
+			// Duration indicates the total duration of this journey.
 			Duration Duration `json:"duration"`
+
+			// Distance indicates the total distance of this journey.
 			Distance Distance `json:"distance"`
 		} `json:"elements"`
 	} `json:"rows"`