Merge lp:~teknico/ubuntu-push/tweak-docs into lp:ubuntu-push

[Nicola Larosa]

Clean up docs and comments, and make them look better in go doc. No behavior change at all.

Clean up docs and comments, and make them look better in go doc. No behavior change at all.

[Samuele Pedroni (pedronis)]

review: Approve

=== modified file 'README'
--- README	2014-01-14 15:35:20 +0000
+++ README	2014-02-24 10:30:17 +0000
@@ -1,37 +1,34 @@
 Ubuntu Push Notifications
---------------------------
+-------------------------
 
 Protocol, client, and development code for Ubuntu Push Notifications.
 
 The code expects to be checked out as launchpad.net/ubuntu-push in a Go
-workspace, see go help gopath.
+workspace, see "go help gopath".
 
-To setup go dependencies one can use:
+To setup Go dependencies, install libsqlite3-dev and run:
 
    make bootstrap
 
-To run tests:
+To run tests, install libgcrypt11-dev and libwhoopsie-dev and run:
 
    make check
 
-To produce coverage reports go 1.2 (default on trusty) is needed and
+To produce coverage reports you need Go 1.2 (default on Trusty) and
 the cover tool (the latter can be obtained atm with something like:
-sudo GOPATH=<go-workspace> go get code.google.com/p/go.tools/cmd/cover
-)
-
+sudo GOPATH=<go-workspace> go get code.google.com/p/go.tools/cmd/cover ),
 then run:
 
    make coverage-summary
 
 for a summary report, or:
 
-for per package html with annotated code in coverhtml/<package-name>.html
+for per-package HTML with annotated code in coverhtml/<package-name>.html
 
   make coverage-html
 
 (it makes also textual coverhtml/<package-name>.txt reports).
 
-To run the acceptance tests, go into the acceptance subdir and run:
+To run the acceptance tests, change to the acceptance subdir and run:
 
    ./acceptance.sh
-

=== modified file 'bus/connectivity/connectivity.go'
--- bus/connectivity/connectivity.go	2014-02-24 10:30:17 +0000
+++ bus/connectivity/connectivity.go	2014-02-24 10:30:17 +0000
@@ -14,8 +14,8 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package connectivity a single, simple stream of booleans
-// to answer the quesiton “are we connected?”.
+// Package connectivity implements a single, simple stream of booleans
+// to answer the question "are we connected?".
 //
 // It can potentially fire two falses in a row, if a disconnected
 // state is followed by a dbus watch error. Other than that, it's edge
@@ -32,7 +32,7 @@
 	"time"
 )
 
-// the configuration for ConnectedState, with the idea that you'd populate it from a config file.
+// The configuration for ConnectedState, intended to be populated from a config file.
 type ConnectivityConfig struct {
 	// how long to wait after a state change to make sure it's "stable"
 	// before acting on it

=== modified file 'bus/connectivity/connectivity_test.go'
--- bus/connectivity/connectivity_test.go	2014-02-05 18:17:26 +0000
+++ bus/connectivity/connectivity_test.go	2014-02-24 10:30:17 +0000
@@ -74,7 +74,7 @@
 	c.Check(cs.connAttempts, Equals, uint32(3)) // 1 more than the Fail2Work
 }
 
-// when the calls to NetworkManager fail for a bit, we're still OK
+// when the calls to NetworkManager fails for a bit, we're still OK
 func (s *ConnSuite) TestStartRetriesCall(c *C) {
 	endp := testingbus.NewTestingEndpoint(condition.Work(true), condition.Fail2Work(5), uint32(networkmanager.Connecting))
 	cs := connectedState{config: ConnectivityConfig{}, log: s.log, endp: endp}
@@ -84,7 +84,7 @@
 	c.Check(cs.connAttempts, Equals, uint32(6))
 }
 
-// when ... and bear with me ... the bus works, and the first call to
+// when... and bear with me... the bus works, and the first call to
 // get network manager's state works, but then you can't establish the
 // watch, we recover and try again.
 func (s *ConnSuite) TestStartRetriesWatch(c *C) {

=== modified file 'bus/endpoint.go'
--- bus/endpoint.go	2014-02-06 07:59:27 +0000
+++ bus/endpoint.go	2014-02-24 10:30:17 +0000
@@ -101,9 +101,9 @@
 	return nil
 }
 
-// WatchSignal() takes a member name and sets up a watch for it (on the name,
+// WatchSignal() takes a member name, sets up a watch for it (on the name,
 // path and interface provided when creating the endpoint), and then calls f()
-// with the unpacked value. If it's unable to set up the watch it'll return an
+// with the unpacked value. If it's unable to set up the watch it returns an
 // error. If the watch fails once established, d() is called. Typically f()
 // sends the values over a channel, and d() would close the channel.
 func (endp *endpoint) WatchSignal(member string, f func(...interface{}), d func()) error {

=== modified file 'bus/testing/testing_bus.go'
--- bus/testing/testing_bus.go	2014-01-23 14:33:08 +0000
+++ bus/testing/testing_bus.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package bus/testing provides an implementation of bus.Bus and bus.Endpoint
+// Package testing provides an implementation of bus.Bus and bus.Endpoint
 // suitable for testing.
 package testing
 

=== modified file 'client/client.go'
--- client/client.go	2014-02-08 18:26:49 +0000
+++ client/client.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// The client package implements the Ubuntu Push Notifications client-side
+// Package client implements the Ubuntu Push Notifications client-side
 // daemon.
 package client
 

=== modified file 'client/session/levelmap/levelmap.go'
--- client/session/levelmap/levelmap.go	2014-02-12 13:52:19 +0000
+++ client/session/levelmap/levelmap.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// levelmap holds implementations of the LevelMap that the client
+// Package levelmap holds implementations of the LevelMap that the client
 // session uses to keep track of what messages it has seen.
 package levelmap
 

=== modified file 'client/session/session.go'
--- client/session/session.go	2014-02-12 16:56:18 +0000
+++ client/session/session.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// The client/session package handles the minutiae of interacting with
+// Package session handles the minutiae of interacting with
 // the Ubuntu Push Notifications server.
 package session
 

=== modified file 'config/config.go'
--- config/config.go	2014-01-21 21:35:21 +0000
+++ config/config.go	2014-02-24 10:30:17 +0000
@@ -95,10 +95,10 @@
 }
 
 // ReadConfig reads a JSON configuration into destConfig which should
-// be a pointer to a structure, it does some more configuration
-// specific error checking than plain JSON decoding and mentions
-// fields in errors . Configuration fields are expected to start with
-// lower case in the JSON object.
+// be a pointer to a structure. It does some more configuration
+// specific error checking than plain JSON decoding, and mentions
+// fields in errors. Configuration fields in the JSON object are
+// expected to start with lower case.
 func ReadConfig(r io.Reader, destConfig interface{}) error {
 	destValue, err := checkDestConfig(destConfig)
 	if err != nil {
@@ -182,7 +182,7 @@
 	return uint(cqs)
 }
 
-// LoadFile reads  a file possibly relative to a base dir.
+// LoadFile reads a file possibly relative to a base dir.
 func LoadFile(p, baseDir string) ([]byte, error) {
 	if p == "" {
 		return nil, nil

=== modified file 'logger/logger.go'
--- logger/logger.go	2014-02-06 11:23:36 +0000
+++ logger/logger.go	2014-02-24 10:30:17 +0000
@@ -27,16 +27,16 @@
 
 // Logger is a simple logger interface with logging at levels.
 type Logger interface {
-	// (Re)xpose base Output for logging events.
+	// Re-expose base Output for logging events.
 	Output(calldept int, s string) error
 	// Errorf logs an error.
 	Errorf(format string, v ...interface{})
-	// Fatalf logs an error and exists the program with os.Exit(1).
+	// Fatalf logs an error and exits the program with os.Exit(1).
 	Fatalf(format string, v ...interface{})
-	// PanicStackf logs a error message and a stacktrace, for use
+	// PanicStackf logs an error message and a stacktrace, for use
 	// in panic recovery.
 	PanicStackf(format string, v ...interface{})
-	// Infof logs a info message.
+	// Infof logs an info message.
 	Infof(format string, v ...interface{})
 	// Debugf logs a debug message.
 	Debugf(format string, v ...interface{})
@@ -59,13 +59,13 @@
 	"debug": lDebug,
 }
 
-// MinimalLogger is the  minimal interface required to build a simple logger on top.
+// MinimalLogger is the  minimal interface required to build a simple logger.
 type MinimalLogger interface {
 	Output(calldepth int, s string) error
 }
 
 // NewSimpleLoggerFromMinimalLogger creates a logger logging only up
-// to the given level. level can be in order: "error", "info",
+// to the given level. The level can be, in order: "error", "info",
 // "debug". It takes a value just implementing stlib Logger.Output().
 func NewSimpleLoggerFromMinimalLogger(minLog MinimalLogger, level string) Logger {
 	nlevel := levelToNLevel[level]
@@ -76,7 +76,7 @@
 }
 
 // NewSimpleLogger creates a logger logging only up to the given
-// level. level can be in order: "error", "info", "debug". It takes a
+// level. The level can be, in order: "error", "info", "debug". It takes an
 // io.Writer.
 func NewSimpleLogger(w io.Writer, level string) Logger {
 	return NewSimpleLoggerFromMinimalLogger(

=== modified file 'protocol/messages.go'
--- protocol/messages.go	2014-01-15 15:54:20 +0000
+++ protocol/messages.go	2014-02-24 10:30:17 +0000
@@ -16,14 +16,13 @@
 
 package protocol
 
-// representative struct for messages
+// Struct representing messages.
 
 import (
 	"encoding/json"
-	// "log"
 )
 
-//  System channel id using a shortened hex encoded form for the NIL UUID
+// System channel id using a shortened hex-encoded form for the NIL UUID.
 const SystemChannelId = "0"
 
 // CONNECT message
@@ -43,7 +42,7 @@
 }
 
 // ConnAckParams carries the connection parameters from the server on
-// connection acknowledment.
+// connection acknowledgement.
 type ConnAckParams struct {
 	// ping interval formatted time.Duration
 	PingInterval string
@@ -108,7 +107,7 @@
 	Payload json.RawMessage `json:"P"`
 }
 
-// ACKnowelgement message
+// ACKnowledgement message
 type AckMsg struct {
 	Type string `json:"T"`
 }

=== modified file 'protocol/protocol.go'
--- protocol/protocol.go	2014-02-24 10:30:17 +0000
+++ protocol/protocol.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package protocol has code to talk the client-daemon<->push-server protocol.
+// Package protocol implements the client-daemon <-> push-server protocol.
 package protocol
 
 import (
@@ -64,7 +64,7 @@
 		conn:   conn}
 }
 
-// SetDeadline sets deadline for the subsquent WriteMessage/ReadMessage exchange
+// SetDeadline sets deadline for the subsequent WriteMessage/ReadMessage exchange.
 func (c *protocol0) SetDeadline(t time.Time) {
 	err := c.conn.SetDeadline(t)
 	if err != nil {
@@ -72,8 +72,8 @@
 	}
 }
 
-// ReadMessage reads one message made of big endian uint16 length, JSON body
-// of length from the connection.
+// ReadMessage reads one message with big-endian uint16 length and JSON body
+// from the connection.
 func (c *protocol0) ReadMessage(msg interface{}) error {
 	c.buffer.Reset()
 	_, err := io.CopyN(c.buffer, c.conn, 2)
@@ -89,8 +89,8 @@
 	return json.Unmarshal(c.buffer.Bytes(), msg)
 }
 
-// WriteMessage writes one message made of big endian uint16 length, JSON body
-// of length to the connection.
+// WriteMessage writes one message with big-endian uint16 length and JSON body
+// to the connection.
 func (c *protocol0) WriteMessage(msg interface{}) error {
 	c.buffer.Reset()
 	c.buffer.WriteString("\x00\x00") // placeholder for length

=== modified file 'protocol/protocol_test.go'
--- protocol/protocol_test.go	2014-02-10 22:53:00 +0000
+++ protocol/protocol_test.go	2014-02-24 10:30:17 +0000
@@ -19,7 +19,6 @@
 import (
 	"encoding/binary"
 	"encoding/json"
-	// "fmt"
 	"io"
 	"net"
 	"testing"

=== modified file 'scripts/check_fmt'
--- scripts/check_fmt	2014-01-14 15:35:20 +0000
+++ scripts/check_fmt	2014-02-24 10:30:17 +0000
@@ -1,6 +1,6 @@
 #!/bin/bash
-# check that all go files respect gofmt formatting
-# assumes GOPATH is properly set
+# Checks that all Go files in the specified project respect gofmt formatting.
+# Requires GOPATH to be set to a single path, not a list of them.
 PROJECT=${1:?missing project}
 PROBLEMS=
 for pkg in $(go list ${PROJECT}/...) ; do

=== modified file 'server/acceptance/acceptanceclient.go'
--- server/acceptance/acceptanceclient.go	2014-02-10 23:19:08 +0000
+++ server/acceptance/acceptanceclient.go	2014-02-24 10:30:17 +0000
@@ -14,6 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+// Package acceptance contains the acceptance client.
 package acceptance
 
 import (

=== modified file 'server/acceptance/cmd/acceptanceclient.go'
--- server/acceptance/cmd/acceptanceclient.go	2014-02-10 23:19:08 +0000
+++ server/acceptance/cmd/acceptanceclient.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// acceptanceclient for playing
+// acceptanceclient command for playing.
 package main
 
 import (

=== modified file 'server/acceptance/config/README'
--- server/acceptance/config/README	2014-01-14 15:35:20 +0000
+++ server/acceptance/config/README	2014-02-24 10:30:17 +0000
@@ -1,7 +1,8 @@
 testing.key/testing.cert
--------------------------
-generated with:
-
-go run /usr/lib/go/src/pkg/crypto/tls/generate_cert.go -ca -host localhost -rsa-bits 512 -duration 87600h
-
-and then renamed
+------------------------
+
+Generated with:
+
+  go run /usr/lib/go/src/pkg/crypto/tls/generate_cert.go -ca -host localhost -rsa-bits 512 -duration 87600h
+
+and then renamed.

=== modified file 'server/dev/server.go'
--- server/dev/server.go	2014-02-18 14:19:05 +0000
+++ server/dev/server.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// simple development server.
+// Server is a simple development server.
 package main
 
 import (

=== modified file 'testing/condition/condition.go'
--- testing/condition/condition.go	2014-02-01 20:57:27 +0000
+++ testing/condition/condition.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package testing/condition implements a strategy family for use in testing.
+// Package condition implements a strategy family for use in testing.
 package condition
 
 import (

=== modified file 'util/redialer.go'
--- util/redialer.go	2014-02-05 12:55:49 +0000
+++ util/redialer.go	2014-02-24 10:30:17 +0000
@@ -14,6 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+// Package util contains the redialer.
 package util
 
 import (
@@ -22,7 +23,7 @@
 )
 
 // A Dialer is an object that knows how to establish a connection, and
-// where you'd usually want some kind of back off if that connection
+// where you'd usually want some kind of backoff if that connection
 // fails.
 type Dialer interface {
 	Dial() error
@@ -39,16 +40,16 @@
 var timeouts []time.Duration
 var trwlock sync.RWMutex
 
-// retrieve the list of timeouts used for exponential backoff
+// Retrieve the list of timeouts used for exponential backoff.
 func Timeouts() []time.Duration {
 	trwlock.RLock()
 	defer trwlock.RUnlock()
 	return timeouts
 }
 
-// for testing: change the default timeouts for the provided ones,
+// For testing: change the default timeouts with the provided ones,
 // returning the defaults (the idea being you reset them on test
-// teardown)
+// teardown).
 func SwapTimeouts(newTimeouts []time.Duration) (oldTimeouts []time.Duration) {
 	trwlock.Lock()
 	defer trwlock.Unlock()
@@ -57,8 +58,8 @@
 }
 
 // An AutoRedialer's Redial() method retries its dialer's Dial() method until
-// it stops returning an error. It does exponential (optionally jitter'ed)
-// backoff.
+// it stops returning an error. It does exponential backoff (optionally
+// jittered).
 type AutoRedialer interface {
 	Redial() uint32 // Redial keeps on calling Dial until it stops returning an error.
 	Stop()          // Stop shuts down the given AutoRedialer, if it is still retrying.
@@ -89,10 +90,10 @@
 }
 
 // Redial keeps on calling Dial until it stops returning an error.  It does
-// exponential backoff, adding the output of Jitter at each step back.
+// exponential backoff, adding back the output of Jitter at each step.
 func (ar *autoRedialer) Redial() uint32 {
 	if ar == nil {
-		// at least it's better than the segfault...
+		// at least it's better than a segfault...
 		panic("you can't Redial a nil AutoRedialer")
 	}
 	if ar.stop == nil {
@@ -129,7 +130,7 @@
 	}
 }
 
-// returns a stoppable AutoRedialer using the provided Dialer. If the Dialer
+// Returns a stoppable AutoRedialer using the provided Dialer. If the Dialer
 // is also a Jitterer, the backoff will be jittered.
 func NewAutoRedialer(dialer Dialer) AutoRedialer {
 	ar := &autoRedialer{stop: make(chan bool), dial: dialer.Dial}

=== added file 'whoopsie/doc.go'
--- whoopsie/doc.go	1970-01-01 00:00:00 +0000
+++ whoopsie/doc.go	2014-02-24 10:30:17 +0000
@@ -0,0 +1,18 @@
+/*
+ Copyright 2013-2014 Canonical Ltd.
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 3, as published
+ by the Free Software Foundation.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranties of
+ MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+// Package whoopsie wraps libwhoopsie.
+package whoopsie

=== modified file 'whoopsie/identifier/identifier.go'
--- whoopsie/identifier/identifier.go	2014-02-03 12:23:56 +0000
+++ whoopsie/identifier/identifier.go	2014-02-24 10:30:17 +0000
@@ -14,7 +14,7 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package whoopsie/identifier wraps libwhoopsie, and is thus the
+// Package identifier wraps libwhoopsie, and is thus the
 // source of an anonymous and stable system id used by the Ubuntu
 // error tracker and the Ubuntu push notifications service.
 package identifier

=== modified file 'whoopsie/identifier/testing/testing.go'
--- whoopsie/identifier/testing/testing.go	2014-01-15 15:51:50 +0000
+++ whoopsie/identifier/testing/testing.go	2014-02-24 10:30:17 +0000
@@ -14,8 +14,8 @@
  with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-// Package whoopsie/identifier/testing implements a couple of Ids that
-// are useful for testing things that use whoopsie/identifier.
+// Package testing implements a couple of Ids that are useful
+// for testing things that use whoopsie/identifier.
 package testing
 
 import "errors"

=== modified file 'whoopsie/identifier/testing/testing_test.go'
--- whoopsie/identifier/testing/testing_test.go	2014-01-15 15:51:50 +0000
+++ whoopsie/identifier/testing/testing_test.go	2014-02-24 10:30:17 +0000
@@ -29,41 +29,41 @@
 
 var _ = Suite(&IdentifierSuite{})
 
-// TestSettableDefaultValueVisible tests SettableIdentifier's default
+// TestSettableDefaultValueVisible tests that SettableIdentifier's default
 // value is notable.
 func (s *IdentifierSuite) TestSettableDefaultValueVisible(c *C) {
 	id := Settable()
 	c.Check(id.String(), Equals, "<Settable>")
 }
 
-// TestSettableSets tests SettableIdentifier is settable.
+// TestSettableSets tests that SettableIdentifier is settable.
 func (s *IdentifierSuite) TestSettableSets(c *C) {
 	id := Settable()
 	id.Set("hello")
 	c.Check(id.String(), Equals, "hello")
 }
 
-// TestSettableGenerateDoesNotFail tests SettableIdentifier's Generate
+// TestSettableGenerateDoesNotFail tests that SettableIdentifier's Generate
 // does not fail.
 func (s *IdentifierSuite) TestSettableGenerateDoesNotFail(c *C) {
 	id := Settable()
 	c.Check(id.Generate(), Equals, nil)
 }
 
-// TestFailingFails tests FailingIdentifier fails.
+// TestFailingFails tests that FailingIdentifier fails.
 func (s *IdentifierSuite) TestFailingFails(c *C) {
 	id := Failing()
 	c.Check(id.Generate(), Not(Equals), nil)
 }
 
-// TestFailingStringNotEmpty tests FailingIdentifier still has a
+// TestFailingStringNotEmpty tests that FailingIdentifier still has a
 // non-empty string.
 func (s *IdentifierSuite) TestFailingStringNotEmpty(c *C) {
 	id := Failing()
 	c.Check(id.String(), Equals, "<Failing>")
 }
 
-// TestIdentifierInterface tests FailingIdentifier and
+// TestIdentifierInterface tests that FailingIdentifier and
 // SettableIdentifier implement Id.
 func (s *IdentifierSuite) TestIdentifierInterface(c *C) {
 	_ = []identifier.Id{Failing(), Settable()}