From: Florian Forster <ff@octo.it>
Date: Wed, 31 Jan 2018 15:33:09 +0000 (+0100)
Subject: Package fitbit: Add documentation.
X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=0b5456de50f3e76354cb3222fa16a7dfd5b066bf;p=kraftakt.git

Package fitbit: Add documentation.
---

diff --git a/fitbit/fitbit.go b/fitbit/fitbit.go
index 7e38bf1..33f2ccd 100644
--- a/fitbit/fitbit.go
+++ b/fitbit/fitbit.go
@@ -1,3 +1,4 @@
+// Package fitbit implements functions to interact with the Fitbit API.
 package fitbit
 
 import (
@@ -34,10 +35,14 @@ func oauthConfig() *oauth2.Config {
 	}
 }
 
+// AuthURL returns the URL of the Fitbit consent screen. Users are redirected
+// there to approve Fitbit minting an OAuth2 token for us.
 func AuthURL(ctx context.Context, u *app.User) string {
 	return oauthConfig().AuthCodeURL(u.Sign("Fitbit"), oauth2.AccessTypeOffline)
 }
 
+// ParseToken parses the request of the user being redirected back from the
+// consent screen. The parsed token is stored in u using SetToken().
 func ParseToken(ctx context.Context, r *http.Request, u *app.User) error {
 	if state := r.FormValue("state"); state != u.Sign("Fitbit") {
 		return fmt.Errorf("invalid state parameter: %q", state)
@@ -51,6 +56,9 @@ func ParseToken(ctx context.Context, r *http.Request, u *app.User) error {
 	return u.SetToken(ctx, "Fitbit", tok)
 }
 
+// CheckSignature validates that rawSig is a valid signature of payload. This
+// is used by the Fitbit API to ansure that the receiver can verify that the
+// sender has access to the OAuth2 client secret.
 func CheckSignature(ctx context.Context, payload []byte, rawSig string) bool {
 	signatureGot, err := base64.StdEncoding.DecodeString(rawSig)
 	if err != nil {
@@ -160,6 +168,9 @@ func NewClient(ctx context.Context, fitbitUserID string, u *app.User) (*Client,
 	}, nil
 }
 
+// ActivitySummary returns the daily activity summary.
+//
+// See https://dev.fitbit.com/build/reference/web-api/activity/#get-daily-activity-summary for details.
 func (c *Client) ActivitySummary(ctx context.Context, date string) (*ActivitySummary, error) {
 	url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/activities/date/%s.json",
 		c.fitbitUserID, date)
@@ -188,11 +199,17 @@ func (c *Client) subscriberID(collection string) string {
 	return fmt.Sprintf("%s:%s", c.appUser.ID, collection)
 }
 
+// UserFromSubscriberID parses the user ID from the subscriber ID and calls
+// app.UserByID() with the user ID.
 func UserFromSubscriberID(ctx context.Context, subscriberID string) (*app.User, error) {
 	uid := strings.Split(subscriberID, ":")[0]
 	return app.UserByID(ctx, uid)
 }
 
+// Subscribe subscribes to one collection of the user. It uses a per-collection
+// subscription ID so that we can subscribe to more than one collection.
+//
+// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#adding-a-subscription for details.
 func (c *Client) Subscribe(ctx context.Context, collection string) error {
 	url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions/%s.json",
 		c.fitbitUserID, collection, c.subscriberID(collection))
@@ -244,6 +261,10 @@ func (c *Client) unsubscribe(ctx context.Context, userID, collection, subscripti
 	return nil
 }
 
+// UnsubscribeAll gets a list of all subscriptions we have with the user's
+// account and deletes all found subscriptions.
+//
+// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#deleting-a-subscription for details.
 func (c *Client) UnsubscribeAll(ctx context.Context) error {
 	var errs appengine.MultiError
 
@@ -267,6 +288,8 @@ func (c *Client) UnsubscribeAll(ctx context.Context) error {
 	return nil
 }
 
+// ListSubscriptions returns a list of all subscriptions for a given collection
+// the OAuth2 client has to a user's account.
 func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Subscription, error) {
 	url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions.json", c.fitbitUserID, collection)
 	res, err := c.client.Get(url)
@@ -325,15 +348,19 @@ func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Su
 	return ret, nil
 }
 
+// DeleteToken deletes the Fitbit OAuth2 token.
 func (c *Client) DeleteToken(ctx context.Context) error {
 	return c.appUser.DeleteToken(ctx, "Fitbit")
 }
 
+// Provile contains data about the user.
+// It only contains the subset of fields required by Kraftakt.
 type Profile struct {
 	Name     string
 	Timezone *time.Location
 }
 
+// Profile returns the profile information of the user.
 func (c *Client) Profile(ctx context.Context) (*Profile, error) {
 	res, err := c.client.Get("https://api.fitbit.com/1/user/-/profile.json")
 	if err != nil {