x/ref: Update package doc for all packages.
This brings all our package doc into a reasonable and consistent
state. To see what it looks like, visit:
http://toddw-linux.mtv.corp.google.com:6060/pkg/v.io/
Note that services/agent is the only remaining package without
reasonable docs. I will update the docs separately, since I
still need to restructure some of its packages.
Change-Id: Id8bc737e3566a0ef3ab110e1245ad30ce1aac121
diff --git a/envvar/envvar.go b/envvar/envvar.go
index 6a755a7..e91a566 100644
--- a/envvar/envvar.go
+++ b/envvar/envvar.go
@@ -2,7 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package envvar defines accessors for the environment variables used by the reference v23 implementation.
+// Package envvar defines the environment variables used by the reference v23
+// implementation.
package envvar
import (
diff --git a/examples/rps/rpsbot/main.go b/examples/rps/rpsbot/main.go
index 8a0fa15..492be26 100644
--- a/examples/rps/rpsbot/main.go
+++ b/examples/rps/rpsbot/main.go
@@ -2,12 +2,10 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Command rpsbot is a binary that runs the fully automated
-// implementation of the RockPaperScissors service, which includes all
-// three roles involved in the game of rock-paper-scissors. It
-// publishes itself as player, judge, and scorekeeper. Then, it
-// initiates games with other players, in a loop. As soon as one game
-// is over, it starts a new one.
+// Command rpsbot repeatedly runs automated games, implementing all three roles.
+// It publishes itself as player, judge, and scorekeeper. Then, it initiates
+// games with other players, in a loop. As soon as one game is over, it starts a
+// new one.
package main
import (
diff --git a/examples/rps/rpsplayer/main.go b/examples/rps/rpsplayer/main.go
index 56122fb..b513d15 100644
--- a/examples/rps/rpsplayer/main.go
+++ b/examples/rps/rpsplayer/main.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Command rpsplayer is a command-line implementation of the Player
-// service that allows a human player to join the game.
+// Command rpsplayer implements the Player interface, which enables a human to
+// play the game.
package main
import (
diff --git a/examples/rps/rpsscorekeeper/main.go b/examples/rps/rpsscorekeeper/main.go
index 329782d..a5611e5 100644
--- a/examples/rps/rpsscorekeeper/main.go
+++ b/examples/rps/rpsscorekeeper/main.go
@@ -2,10 +2,9 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Command rpsscorekeeper is a simple implementation of the
-// ScoreKeeper service. It publishes itself as a score keeper for the
-// rock-paper-scissors game and prints out all the score cards it
-// receives to stdout.
+// Command rpsscorekeeper implements the ScoreKeeper interface. It publishes
+// itself as a score keeper for the rock-paper-scissors game and prints out all
+// the score cards it receives to stdout.
package main
import (
diff --git a/examples/rps/service.vdl b/examples/rps/service.vdl
index f9afda2..b5f9c7c 100644
--- a/examples/rps/service.vdl
+++ b/examples/rps/service.vdl
@@ -2,20 +2,22 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package rps is an example of vanadium service for playing the game of
-// Rock-Paper-Scissors. (http://en.wikipedia.org/wiki/Rock-paper-scissors)
+// Package rps defines interfaces for playing the game Rock-Paper-Scissors. It
+// is an example of a simple Vanadium service.
+//
+// http://en.wikipedia.org/wiki/Rock-paper-scissors
//
// There are three different roles in the game:
//
-// 1. Judge: A judge enforces the rules of the game and decides who
-// the winner is. At the end of the game, the judge reports the
-// final score to all the score keepers.
+// 1. Judge: A judge enforces the rules of the game and decides who the winner
+// is. At the end of the game, the judge reports the final score to all the
+// score keepers.
//
-// 2. Player: A player can ask a judge to start a new game, it can
-// challenge another player, and it can play a game.
+// 2. Player: A player can ask a judge to start a new game, it can challenge
+// another player, and it can play a game.
//
-// 3. ScoreKeeper: A score keeper receives the final score for a game
-// after it ended.
+// 3. ScoreKeeper: A score keeper receives the final score for a game after it
+// ended.
package rps
import (
diff --git a/examples/rps/service.vdl.go b/examples/rps/service.vdl.go
index efa4a4d..7ee0216 100644
--- a/examples/rps/service.vdl.go
+++ b/examples/rps/service.vdl.go
@@ -5,20 +5,22 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: service.vdl
-// Package rps is an example of vanadium service for playing the game of
-// Rock-Paper-Scissors. (http://en.wikipedia.org/wiki/Rock-paper-scissors)
+// Package rps defines interfaces for playing the game Rock-Paper-Scissors. It
+// is an example of a simple Vanadium service.
+//
+// http://en.wikipedia.org/wiki/Rock-paper-scissors
//
// There are three different roles in the game:
//
-// 1. Judge: A judge enforces the rules of the game and decides who
-// the winner is. At the end of the game, the judge reports the
-// final score to all the score keepers.
+// 1. Judge: A judge enforces the rules of the game and decides who the winner
+// is. At the end of the game, the judge reports the final score to all the
+// score keepers.
//
-// 2. Player: A player can ask a judge to start a new game, it can
-// challenge another player, and it can play a game.
+// 2. Player: A player can ask a judge to start a new game, it can challenge
+// another player, and it can play a game.
//
-// 3. ScoreKeeper: A score keeper receives the final score for a game
-// after it ended.
+// 3. ScoreKeeper: A score keeper receives the final score for a game after it
+// ended.
package rps
import (
diff --git a/examples/tunnel/tunnel.vdl b/examples/tunnel/tunnel.vdl
index 24629ba..f1bafcb 100644
--- a/examples/tunnel/tunnel.vdl
+++ b/examples/tunnel/tunnel.vdl
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package tunnel describes a service that can be used to create a
-// network tunnel from the client to the server.
+// Package tunnel defines an interface for creating a network tunnel from client
+// to server.
package tunnel
import "v.io/v23/security/access"
diff --git a/examples/tunnel/tunnel.vdl.go b/examples/tunnel/tunnel.vdl.go
index 6fcca58..7f8cca3 100644
--- a/examples/tunnel/tunnel.vdl.go
+++ b/examples/tunnel/tunnel.vdl.go
@@ -5,8 +5,8 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: tunnel.vdl
-// Package tunnel describes a service that can be used to create a
-// network tunnel from the client to the server.
+// Package tunnel defines an interface for creating a network tunnel from client
+// to server.
package tunnel
import (
diff --git a/examples/tunnel/tunneld/main.go b/examples/tunnel/tunneld/main.go
index 55edc16..f9de51e 100644
--- a/examples/tunnel/tunneld/main.go
+++ b/examples/tunnel/tunneld/main.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Command tunneld is an implementation of the tunnel service.
+// Daemon tunneld implements the Tunnel interface.
package main
import (
diff --git a/examples/tunnel/vsh/main.go b/examples/tunnel/vsh/main.go
index a08c0c3..c038fc5 100644
--- a/examples/tunnel/vsh/main.go
+++ b/examples/tunnel/vsh/main.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Command vsh is a tunnel service client that can be used to start a
-// shell on the server.
+// Command vsh is a Tunnel client that can be used to start a shell on the
+// server.
package main
import (
diff --git a/lib/exec/doc.go b/lib/exec/doc.go
index a490799..b1b464f 100644
--- a/lib/exec/doc.go
+++ b/lib/exec/doc.go
@@ -2,18 +2,17 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package exec implements process creation and rendezvous, including
-// sharing a secret with, and passing arbitrary configuration to, the newly
-// created process via an anoymous pipe. An anonymous pipe is used since
-// it is the most secure communication channel available.
+// Package exec implements configuration and secret-sharing between parent and
+// child processes via anoymous pipes. Anonymous pipes are used since they are
+// the most secure communication channel available.
//
-// Once a parent starts a child process it can use WaitForReady to wait
-// for the child to reach its 'Ready' state. Operations are provided to wait
-// for the child to terminate, and to terminate the child, cleaning up any state
+// Once a parent starts a child process it can use WaitForReady to wait for the
+// child to reach its 'Ready' state. Operations are provided to wait for the
+// child to terminate, and to terminate the child, cleaning up any state
// associated with it.
//
// A child process uses the GetChildHandle function to complete the initial
-// authentication handshake. The child must call SetReady to indicate that it is
-// fully initialized and ready for whatever purpose it is intended to fulfill.
-// This handshake is referred as the 'exec protocol'.
+// authentication handshake. The child must call SetReady to indicate that it
+// is fully initialized and ready for whatever purpose it is intended to
+// fulfill. This handshake is referred as the 'exec protocol'.
package exec
diff --git a/lib/flags/doc.go b/lib/flags/doc.go
index 5af2a64..6d7807a 100644
--- a/lib/flags/doc.go
+++ b/lib/flags/doc.go
@@ -2,17 +2,17 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package flags provides definitions for commonly used flags and, where
-// appropriate, implementations of the flag.Value interface for those flags to
-// ensure that only valid values of those flags are supplied. Some of these
-// flags may also be specified using environment variables directly and are
-// documented accordingly; in these cases the command line value takes
-// precedence over the environment variable.
+// Package flags implements utilities to augment the standard Go flag package.
+// It defines commonly used Vanadium flags, and implementations of the
+// flag.Value interface for those flags to ensure that only valid values of
+// those flags are supplied. Some of these flags may also be specified using
+// environment variables directly and are documented accordingly; in these cases
+// the command line value takes precedence over the environment variable.
//
// Flags are defined as 'groups' of related flags so that the caller may choose
-// which ones to use without having to be burdened with the full set. The groups
-// may be used directly or via the Flags type that aggregates multiple
-// groups. In all cases, the flags are registered with a supplied flag.FlagSet
+// which ones to use without having to be burdened with the full set. The
+// groups may be used directly or via the Flags type that aggregates multiple
+// groups. In all cases, the flags are registered with a supplied flag.FlagSet
// and hence are not forced onto the command line unless the caller passes in
// flag.CommandLine as the flag.FlagSet to use.
//
diff --git a/lib/glob/glob.go b/lib/glob/glob.go
index 7a9e35d..b490715 100644
--- a/lib/glob/glob.go
+++ b/lib/glob/glob.go
@@ -2,24 +2,23 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// glob implements a glob language.
+// Package glob defines a globbing syntax and implements matching routines.
//
// Globs match a slash separated series of glob expressions.
//
-// pattern:
-// term ['/' term]*
-// term:
-// '*' matches any sequence of non-Separator characters
-// '?' matches any single non-Separator character
-// '[' [ '^' ] { character-range } ']'
-// character class (must be non-empty)
-// c matches character c (c != '*', '?', '\\', '[', '/')
-// '\\' c matches character c
-// character-range:
-// c matches character c (c != '\\', '-', ']')
-// '\\' c matches character c
-// lo '-' hi matches character c for lo <= c <= hi
-
+// // Patterns:
+// term ['/' term]*
+// term:
+// '*' matches any sequence of non-Separator characters
+// '?' matches any single non-Separator character
+// '[' [ '^' ] { character-range } ']'
+// // Character classes (must be non-empty):
+// c matches character c (c != '*', '?', '\\', '[', '/')
+// '\\' c matches character c
+// // Character-ranges:
+// c matches character c (c != '\\', '-', ']')
+// '\\' c matches character c
+// lo '-' hi matches character c for lo <= c <= hi
package glob
import (
diff --git a/lib/security/audit/auditor.go b/lib/security/audit/auditor.go
index dbfbba8..c73c9c7 100644
--- a/lib/security/audit/auditor.go
+++ b/lib/security/audit/auditor.go
@@ -2,10 +2,11 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package audit provides mechanisms to write method invocations to an audit log.
+// Package audit implements a mechanism for writing auditable events to an audit
+// log.
//
-// Typical use would be for tracking sensitive operations like private key usage (NewPrincipal),
-// or sensitive RPC method invocations.
+// Typical use would be for tracking sensitive operations like private key usage
+// (NewPrincipal), or sensitive RPC method invocations.
package audit
import (
diff --git a/lib/security/doc.go b/lib/security/doc.go
index ea00908..11c7325 100644
--- a/lib/security/doc.go
+++ b/lib/security/doc.go
@@ -2,5 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package security provides utility functions for creating/using vanadium security primitives.
+// Package security implements utilities for creating and using Vanadium
+// security primitives.
package security
diff --git a/lib/security/securityflag/flag.go b/lib/security/securityflag/flag.go
index 48ee109..c2f6acb 100644
--- a/lib/security/securityflag/flag.go
+++ b/lib/security/securityflag/flag.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package securityflag defines a method for parsing AccessList flags and
-// constructing a security.Authorizer based on them.
+// Package securityflag implements utilities for creating security objects based
+// on flags.
package securityflag
import (
diff --git a/lib/security/serialization/serialization.go b/lib/security/serialization/serialization.go
index b696ad1..f2df90d 100644
--- a/lib/security/serialization/serialization.go
+++ b/lib/security/serialization/serialization.go
@@ -2,8 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package serialization defines a general-purpose io.WriteCloser
-// for writing data along with an appropriate signature that
-// establishes integrity and authenticity of data, and an io.Reader
-// for reading the data after verifying the signature.
+// Package serialization implements utilities for reading and writing data with
+// signature-based integrity checking.
package serialization
diff --git a/lib/signals/signals.go b/lib/signals/signals.go
index 1727dc4..bc645d4 100644
--- a/lib/signals/signals.go
+++ b/lib/signals/signals.go
@@ -2,8 +2,13 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package signals implements utilities for managing process shutdown with
+// support for signal-handling.
package signals
+// TODO(caprita): Rename the function to Shutdown() and the package to shutdown
+// since it's not just signals anymore.
+
import (
"os"
"os/signal"
@@ -49,9 +54,6 @@
return []os.Signal{syscall.SIGTERM, syscall.SIGINT, STOP}
}
-// TODO(caprita): Rename this to Shutdown() and the package to shutdown since
-// it's not just signals anymore.
-
// ShutdownOnSignals registers signal handlers for the specified signals, or, if
// none are specified, the default signals. The first signal received will be
// made available on the returned channel; upon receiving a second signal, the
diff --git a/lib/stats/histogram/histogram.go b/lib/stats/histogram/histogram.go
index c9b329b..285fabc 100644
--- a/lib/stats/histogram/histogram.go
+++ b/lib/stats/histogram/histogram.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// package histogram implements a basic histogram to keep track of data
+// Package histogram implements a basic histogram to keep track of data
// distribution.
package histogram
diff --git a/lib/timekeeper/timekeeper.go b/lib/timekeeper/timekeeper.go
index 88c4c42..2fee233 100644
--- a/lib/timekeeper/timekeeper.go
+++ b/lib/timekeeper/timekeeper.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package timekeeper defines an interface to allow switching between real time
+// and simulated time.
package timekeeper
import "time"
diff --git a/lib/vdl/build/build.go b/lib/vdl/build/build.go
index 07947bb..397ac63 100644
--- a/lib/vdl/build/build.go
+++ b/lib/vdl/build/build.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package build provides utilities to collect VDL build information, and
-// helpers to kick off the parser and compiler.
+// Package build implements utilities to collect VDL build information and run
+// the parser and compiler.
//
// VDL Packages
//
diff --git a/lib/vdl/codegen/doc.go b/lib/vdl/codegen/doc.go
deleted file mode 100644
index 5a8537e..0000000
--- a/lib/vdl/codegen/doc.go
+++ /dev/null
@@ -1,7 +0,0 @@
-// Copyright 2015 The Vanadium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-// Package codegen implements utilities useful for all vdl code generators.
-// Code generators for specific languages live in sub-directories.
-package codegen
diff --git a/lib/vdl/codegen/import.go b/lib/vdl/codegen/import.go
index b25d734..fbe5d23 100644
--- a/lib/vdl/codegen/import.go
+++ b/lib/vdl/codegen/import.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package codegen implements utilities for VDL code generators. Code
+// generators for specific languages live in sub-directories.
package codegen
import (
diff --git a/lib/vdl/compile/compile.go b/lib/vdl/compile/compile.go
index feab45f..dd8cb1d 100644
--- a/lib/vdl/compile/compile.go
+++ b/lib/vdl/compile/compile.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package compile provides utilities to compile vdl files. The Compile
-// function is the main entry point.
+// Package compile implements the VDL compiler, converting a parse tree into
+// compiled results. The CompilePackage function is the main entry point.
package compile
// The job of the compiler is to take parse results as input, and output
diff --git a/lib/vdl/opconst/const.go b/lib/vdl/opconst/const.go
index fa5e04c..f9d0859 100644
--- a/lib/vdl/opconst/const.go
+++ b/lib/vdl/opconst/const.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package opconst provides the representation and operations for vdl constants.
+// Package opconst defines the representation and operations for VDL constants.
package opconst
import (
diff --git a/lib/vdl/parse/parse.go b/lib/vdl/parse/parse.go
index ab74c83..c4f8394 100644
--- a/lib/vdl/parse/parse.go
+++ b/lib/vdl/parse/parse.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package parse provides utilities to parse vdl files into a parse tree. The
-// Parse function is the main entry point.
+// Package parse implements the VDL parser, converting source files into a parse
+// tree. The ParseFile function is the main entry point.
package parse
//go:generate ./grammar_gen.sh
diff --git a/lib/vdl/vdlutil/doc.go b/lib/vdl/vdlutil/doc.go
deleted file mode 100644
index 509458b..0000000
--- a/lib/vdl/vdlutil/doc.go
+++ /dev/null
@@ -1,8 +0,0 @@
-// Copyright 2015 The Vanadium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-// Package vdlutil provides core utilities for vdl files. It's used by the
-// auto-generated Go code, as well as the vdl parser, compiler and code
-// generators; it should have a small set of dependencies.
-package vdlutil
diff --git a/lib/vdl/vdlutil/util.go b/lib/vdl/vdlutil/util.go
index ba68205..1145857 100644
--- a/lib/vdl/vdlutil/util.go
+++ b/lib/vdl/vdlutil/util.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package vdlutil implements utilities used by many VDL components. It should
+// have a small set of dependencies.
package vdlutil
import (
diff --git a/profiles/chrome/chromeinit.go b/profiles/chrome/chromeinit.go
index 5223f6f..6445080 100644
--- a/profiles/chrome/chromeinit.go
+++ b/profiles/chrome/chromeinit.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package chrome implements a profile for use within Chrome, in particular
-// for use by Chrome extensions.
+// Package chrome implements a profile for use within Chrome, in particular for
+// use by Chrome extensions.
package chrome
import (
diff --git a/profiles/doc.go b/profiles/doc.go
index 7a7cdcd..327c5b9 100644
--- a/profiles/doc.go
+++ b/profiles/doc.go
@@ -2,21 +2,16 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package Profiles, and its children, provide implementations of the
-// v23.Profile function. These implementations should import all of the
-// packages that they require to implement Profile-specific functionality.
+// Package profiles and its subdirectories provide implementations of the
+// Vanadium runtime for different runtime environments. Each subdirectory is a
+// package that implements the v23.Profile function.
//
-// The taxonomy used to organise Profiles may be arbitrary and the directory
-// structure used here is just one convention for how to do so. This directory
-// structure reflects the generality of a Profile at any given depth in the
-// hierarchy, with higher levels of the directory structure being more
-// generic and lower levels more specific.
-//
-// Profiles register themselves by calling v.io/v23/rt.RegisterProfile in their
-// init function and are hence are chosen by importing them into an
-// applications main package. It is an error to import more than one profile,
-// and the registration mechanism will panic if this is attempted.
-// Commonly used functionality and pre-canned profiles are in profiles/internal.
+// Profiles register themselves by calling v.io/v23/rt.RegisterProfile in an
+// init function. Users choose a particular profile implementation by importing
+// the appropriate package in their main package. It is an error to import more
+// than one profile, and the registration mechanism will panic if this is
+// attempted. Commonly used functionality and pre-canned profiles are in
+// profiles/internal.
//
// This top level directory contains a 'generic' Profile and utility routines
// used by other Profiles. It should be imported whenever possible and
@@ -26,5 +21,4 @@
// configurations and in particular dhcp. It should be used by any application
// that may 'roam' or any may be behind a 1-1 NAT. The 'static' profile
// does not provide dhcp support, but is otherwise like the roaming profile.
-//
package profiles
diff --git a/profiles/fake/fake.go b/profiles/fake/fake.go
index bae6df8..ddd6a0d 100644
--- a/profiles/fake/fake.go
+++ b/profiles/fake/fake.go
@@ -2,8 +2,12 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package fake implements a fake profile, useful in tests for mocking out
+// certain components.
package fake
+// TODO(mattr): Make a more complete, but still fake, implementation.
+
import (
"sync"
diff --git a/profiles/fake/runtime.go b/profiles/fake/runtime.go
index e2c5cf3..d239b3a 100644
--- a/profiles/fake/runtime.go
+++ b/profiles/fake/runtime.go
@@ -2,9 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// fake implements a fake runtime. The fake runtime is useful in tests when you
-// want to mock out important components.
-// TODO(mattr): Make a more complete, but still fake, implementation.
package fake
import (
diff --git a/profiles/gce/init.go b/profiles/gce/init.go
index e192b72..15c96d3 100644
--- a/profiles/gce/init.go
+++ b/profiles/gce/init.go
@@ -4,8 +4,8 @@
// +build linux
-// Package gce provides a profile for Google Compute Engine and should be
-// used by binaries that only ever expect to be run on GCE.
+// Package gce implements a profile for binaries that only run on Google Compute
+// Engine.
package gce
import (
diff --git a/profiles/roaming/roaminginit.go b/profiles/roaming/roaminginit.go
index 342422d..f09f1c6 100644
--- a/profiles/roaming/roaminginit.go
+++ b/profiles/roaming/roaminginit.go
@@ -4,10 +4,9 @@
// +build linux darwin
-// Package roaming provides a network-aware Profile that provides appropriate
-// options and configuration for a variety of network configurations, including
-// being behind 1-1 NATs, using dhcp and auto-configuration for being on
-// Google Compute Engine.
+// Package roaming implements a profile suitable for a variety of network
+// configurations, including 1-1 NATs, dhcp auto-configuration, and Google
+// Compute Engine.
//
// The config.Publisher mechanism is used for communicating networking
// settings to the rpc.Server implementation of the runtime and publishes
diff --git a/profiles/static/staticinit.go b/profiles/static/staticinit.go
index 7da5a31..1908308 100644
--- a/profiles/static/staticinit.go
+++ b/profiles/static/staticinit.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package static implements a profile for static network configurations.
package static
import (
diff --git a/services/application/application/doc.go b/services/application/application/doc.go
index 72308f7..491f801 100644
--- a/services/application/application/doc.go
+++ b/services/application/application/doc.go
@@ -6,8 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-The application tool facilitates interaction with the vanadium application
-repository.
+Command application manages the Vanadium application repository.
Usage:
application <command>
diff --git a/services/application/application/impl.go b/services/application/application/impl.go
index c0b5e1d..de18364 100644
--- a/services/application/application/impl.go
+++ b/services/application/application/impl.go
@@ -229,10 +229,9 @@
func root() *cmdline.Command {
return &cmdline.Command{
Name: "application",
- Short: "Tool for interacting with the vanadium application repository",
+ Short: "manages the Vanadium application repository",
Long: `
-The application tool facilitates interaction with the vanadium application
-repository.
+Command application manages the Vanadium application repository.
`,
Children: []*cmdline.Command{cmdMatch, cmdPut, cmdRemove, cmdEdit},
}
diff --git a/services/application/applicationd/main.go b/services/application/applicationd/main.go
index d8a0b1d..28a4012 100644
--- a/services/application/applicationd/main.go
+++ b/services/application/applicationd/main.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon applicationd implements the v.io/x/ref/services/repository.Application
+// interface.
package main
import (
diff --git a/services/binary/binary/doc.go b/services/binary/binary/doc.go
index 2a123ea..be451bf 100644
--- a/services/binary/binary/doc.go
+++ b/services/binary/binary/doc.go
@@ -6,7 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-The binary tool facilitates interaction with the vanadium binary repository.
+Command binary manages the Vanadium binary repository.
Usage:
binary <command>
diff --git a/services/binary/binary/impl.go b/services/binary/binary/impl.go
index c166d7b..75e80b4 100644
--- a/services/binary/binary/impl.go
+++ b/services/binary/binary/impl.go
@@ -125,9 +125,9 @@
func root() *cmdline.Command {
return &cmdline.Command{
Name: "binary",
- Short: "Tool for interacting with the vanadium binary repository",
+ Short: "manages the Vanadium binary repository",
Long: `
-The binary tool facilitates interaction with the vanadium binary repository.
+Command binary manages the Vanadium binary repository.
`,
Children: []*cmdline.Command{cmdDelete, cmdDownload, cmdUpload, cmdURL},
}
diff --git a/services/binary/binaryd/main.go b/services/binary/binaryd/main.go
index c62ff3e..e5fdc80 100644
--- a/services/binary/binaryd/main.go
+++ b/services/binary/binaryd/main.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon binaryd implements the v.io/v23/services/repository.Binary interface.
package main
import (
diff --git a/services/build/build/doc.go b/services/build/build/doc.go
index 74b7d8c..def9f75 100644
--- a/services/build/build/doc.go
+++ b/services/build/build/doc.go
@@ -6,7 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-The build tool tool facilitates interaction with the vanadium build server.
+Command build sends commands to a Vanadium build server.
Usage:
build <command>
diff --git a/services/build/build/impl.go b/services/build/build/impl.go
index cedcff6..fbe9391 100644
--- a/services/build/build/impl.go
+++ b/services/build/build/impl.go
@@ -38,9 +38,9 @@
var cmdRoot = &cmdline.Command{
Name: "build",
- Short: "Tool for interacting with the vanadium build server",
+ Short: "sends commands to a Vanadium build server",
Long: `
-The build tool tool facilitates interaction with the vanadium build server.
+Command build sends commands to a Vanadium build server.
`,
Children: []*cmdline.Command{cmdBuild},
}
diff --git a/services/build/buildd/main.go b/services/build/buildd/main.go
index c2b05de..71edc14 100644
--- a/services/build/buildd/main.go
+++ b/services/build/buildd/main.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon buildd implements the v.io/v23/services/build.Builder interface.
package main
import (
diff --git a/services/debug/debug/doc.go b/services/debug/debug/doc.go
index e6c7173..7034069 100644
--- a/services/debug/debug/doc.go
+++ b/services/debug/debug/doc.go
@@ -6,7 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-Command-line tool for interacting with the debug server.
+Command debug supports debugging Vanadium servers.
Usage:
debug <command>
diff --git a/services/debug/debug/impl.go b/services/debug/debug/impl.go
index a3ee88d..757c91c 100644
--- a/services/debug/debug/impl.go
+++ b/services/debug/debug/impl.go
@@ -548,8 +548,8 @@
var cmdRoot = cmdline.Command{
Name: "debug",
- Short: "Command-line tool for interacting with the debug server.",
- Long: "Command-line tool for interacting with the debug server.",
+ Short: "supports debugging Vanadium servers.",
+ Long: "Command debug supports debugging Vanadium servers.",
Children: []*cmdline.Command{
cmdGlob,
cmdVtrace,
diff --git a/services/debug/debuglib/dispatcher.go b/services/debug/debuglib/dispatcher.go
index d49a531..ce4dc26 100644
--- a/services/debug/debuglib/dispatcher.go
+++ b/services/debug/debuglib/dispatcher.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package debuglib implements debug server support.
package debuglib
import (
diff --git a/services/device/device/doc.go b/services/device/device/doc.go
index 81a7276..c480646 100644
--- a/services/device/device/doc.go
+++ b/services/device/device/doc.go
@@ -6,7 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-The device tool facilitates interaction with the vanadium device manager.
+Command device facilitates interaction with the Vanadium device manager.
Usage:
device <command>
diff --git a/services/device/device/root.go b/services/device/device/root.go
index c65b317..8f680c1 100644
--- a/services/device/device/root.go
+++ b/services/device/device/root.go
@@ -19,9 +19,9 @@
func Root() *cmdline.Command {
return &cmdline.Command{
Name: "device",
- Short: "Tool for interacting with the vanadium device manager",
+ Short: "facilitates interaction with the Vanadium device manager",
Long: `
-The device tool facilitates interaction with the vanadium device manager.
+Command device facilitates interaction with the Vanadium device manager.
`,
Children: []*cmdline.Command{cmdInstall, cmdInstallLocal, cmdUninstall, cmdStart, associateRoot(), cmdDescribe, cmdClaim, cmdStop, cmdSuspend, cmdResume, cmdRevert, cmdUpdate, cmdUpdateAll, cmdStatus, cmdDebug, aclRoot(), cmdPublish},
}
diff --git a/services/device/deviced/main.go b/services/device/deviced/main.go
index b63d710..1e23e55 100644
--- a/services/device/deviced/main.go
+++ b/services/device/deviced/main.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon deviced implements the v.io/v23/services/device interfaces.
package main
import (
diff --git a/services/device/doc.go b/services/device/doc.go
index 92919c7..6309631 100644
--- a/services/device/doc.go
+++ b/services/device/doc.go
@@ -2,7 +2,9 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package device contains the implementation for the v.io/v23//mgmt/device APIs.
+// Package device defines interfaces for configuration of the Vanadium device
+// manager. The subdirectories implement the v.io/v23/services/device
+// interfaces.
//
// The device manager is a server that is expected to run on every
// Vanadium-enabled device, and it handles both device management and management
diff --git a/services/device/inithelper/main.go b/services/device/inithelper/main.go
index 207ce27..7e3301e 100644
--- a/services/device/inithelper/main.go
+++ b/services/device/inithelper/main.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Command inithelper manages services for a variety of platforms and init
+// systems, such as upstart, systemd etc.
package main
// TODO(caprita): The separation of responsibilities between root/non-root code
diff --git a/services/device/suidhelper/main.go b/services/device/suidhelper/main.go
index d0f3022..bde6625 100644
--- a/services/device/suidhelper/main.go
+++ b/services/device/suidhelper/main.go
@@ -2,10 +2,10 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Command suidhelper runs the provided command as the specified user identity.
+// It should be installed setuid root.
package main
-// suidhelper should be installed setuid root. Having done this, it will
-// run the provided command as the specified user identity.
// suidhelper deliberately attempts to be as simple as possible to
// simplify reviewing it for security concerns.
diff --git a/services/discharger/discharger.vdl b/services/discharger/discharger.vdl
index 7aed262..c04ae3a 100644
--- a/services/discharger/discharger.vdl
+++ b/services/discharger/discharger.vdl
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package discharger defines an interface for obtaining discharges for
+// third-party caveats.
package discharger
import "v.io/v23/security"
diff --git a/services/discharger/discharger.vdl.go b/services/discharger/discharger.vdl.go
index 1024842..0729ecc 100644
--- a/services/discharger/discharger.vdl.go
+++ b/services/discharger/discharger.vdl.go
@@ -5,6 +5,8 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: discharger.vdl
+// Package discharger defines an interface for obtaining discharges for
+// third-party caveats.
package discharger
import (
diff --git a/services/groups/groupsd/main.go b/services/groups/groupsd/main.go
index 39222de..ab59f78 100644
--- a/services/groups/groupsd/main.go
+++ b/services/groups/groupsd/main.go
@@ -2,7 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Daemon groupsd manages groups for access control.
+// Daemon groupsd implements the v.io/v23/services/groups interfaces for
+// managing access control groups.
package main
// Example invocation:
diff --git a/services/identity/identity.vdl b/services/identity/identity.vdl
index f761fad..5b265b5 100644
--- a/services/identity/identity.vdl
+++ b/services/identity/identity.vdl
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package identity defines services for identity providers in the vanadium ecosystem.
+// Package identity defines interfaces for Vanadium identity providers.
package identity
import "v.io/v23/security"
diff --git a/services/identity/identity.vdl.go b/services/identity/identity.vdl.go
index 08a329c..f8c2b27 100644
--- a/services/identity/identity.vdl.go
+++ b/services/identity/identity.vdl.go
@@ -5,7 +5,7 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: identity.vdl
-// Package identity defines services for identity providers in the vanadium ecosystem.
+// Package identity defines interfaces for Vanadium identity providers.
package identity
import (
diff --git a/services/identity/identityd/main.go b/services/identity/identityd/main.go
index 5b9f07c..1c57547 100644
--- a/services/identity/identityd/main.go
+++ b/services/identity/identityd/main.go
@@ -2,7 +2,9 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// HTTP server that uses OAuth to create security.Blessings objects.
+// Daemon identityd is an HTTP server that uses OAuth to create
+// security.Blessings objects.
+//
// For more information on our setup of the identity server see:
// https://docs.google.com/document/d/1ebQ1sQn95cFu8yQM36rpJ8mQvsU29aa1o03ADhi52BM
package main
diff --git a/services/identity/identitylib/test_identityd.go b/services/identity/identitylib/test_identityd.go
index 6287264..53c8587 100644
--- a/services/identity/identitylib/test_identityd.go
+++ b/services/identity/identitylib/test_identityd.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package identitylib implements a test identityd service under the
+// v.io/x/ref/test/modules framework.
package identitylib
import (
diff --git a/services/mounttable/mounttabled/mounttable.go b/services/mounttable/mounttabled/mounttable.go
index d2afd5a..7dc5759 100644
--- a/services/mounttable/mounttabled/mounttable.go
+++ b/services/mounttable/mounttabled/mounttable.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// mounttabled is a mount table daemon.
+// Daemon mounttabled implements the v.io/v23/services/mounttable interfaces.
package main
import (
diff --git a/services/mounttable/mounttablelib/mounttable.go b/services/mounttable/mounttablelib/mounttable.go
index 6e1c19d..2d8a28a 100644
--- a/services/mounttable/mounttablelib/mounttable.go
+++ b/services/mounttable/mounttablelib/mounttable.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package mounttablelib implements utilities for mounttable implementations.
package mounttablelib
import (
diff --git a/services/profile/profile.vdl b/services/profile/profile.vdl
index 5b783b7..c2b91a5 100644
--- a/services/profile/profile.vdl
+++ b/services/profile/profile.vdl
@@ -2,8 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package profile contains implementation and internal interfaces and
-// types used by the implementation of Vanadium profiles.
+// Package profile defines types for the implementation of Vanadium profiles.
package profile
import "v.io/v23/services/build"
diff --git a/services/profile/profile.vdl.go b/services/profile/profile.vdl.go
index def9418..f5e27f9 100644
--- a/services/profile/profile.vdl.go
+++ b/services/profile/profile.vdl.go
@@ -5,8 +5,7 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: profile.vdl
-// Package profile contains implementation and internal interfaces and
-// types used by the implementation of Vanadium profiles.
+// Package profile defines types for the implementation of Vanadium profiles.
package profile
import (
diff --git a/services/profile/profile/doc.go b/services/profile/profile/doc.go
index c6d7e2d..0b5995c 100644
--- a/services/profile/profile/doc.go
+++ b/services/profile/profile/doc.go
@@ -6,7 +6,7 @@
// DO NOT UPDATE MANUALLY
/*
-The profile tool facilitates interaction with the vanadium profile repository.
+Command profile manages the Vanadium profile repository.
Usage:
profile <command>
diff --git a/services/profile/profile/impl.go b/services/profile/profile/impl.go
index 03bc0ef..393726d 100644
--- a/services/profile/profile/impl.go
+++ b/services/profile/profile/impl.go
@@ -151,9 +151,9 @@
func root() *cmdline.Command {
return &cmdline.Command{
Name: "profile",
- Short: "Tool for interacting with the vanadium profile repository",
+ Short: "manages the Vanadium profile repository",
Long: `
-The profile tool facilitates interaction with the vanadium profile repository.
+Command profile manages the Vanadium profile repository.
`,
Children: []*cmdline.Command{cmdLabel, cmdDescription, cmdSpecification, cmdPut, cmdRemove},
}
diff --git a/services/profile/profiled/main.go b/services/profile/profiled/main.go
index ab1ab3d..381edec 100644
--- a/services/profile/profiled/main.go
+++ b/services/profile/profiled/main.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon profiled implements the v.io/x/ref/services/repository.Profile
+// interface.
package main
import (
diff --git a/services/proxy/proxyd/main.go b/services/proxy/proxyd/main.go
index 57e9377..c454b68 100644
--- a/services/proxy/proxyd/main.go
+++ b/services/proxy/proxyd/main.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// proxyd is a daemon that listens for connections from vanadium services
-// (typically behind NATs) and proxies these services to the outside world.
+// Daemon proxyd listens for connections from Vanadium services (typically
+// behind NATs) and proxies these services to the outside world.
package main
import (
diff --git a/services/repository/repository.vdl b/services/repository/repository.vdl
index fd4961a..0e4cf1b 100644
--- a/services/repository/repository.vdl
+++ b/services/repository/repository.vdl
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package repository contains implementation of the interface for
-// storing and serving various vanadium management objects.
+// Package repository augments the v.io/v23/services/repository interfaces with
+// implementation-specific configuration methods.
package repository
import (
diff --git a/services/repository/repository.vdl.go b/services/repository/repository.vdl.go
index 806c856..55d0546 100644
--- a/services/repository/repository.vdl.go
+++ b/services/repository/repository.vdl.go
@@ -5,8 +5,8 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: repository.vdl
-// Package repository contains implementation of the interface for
-// storing and serving various vanadium management objects.
+// Package repository augments the v.io/v23/services/repository interfaces with
+// implementation-specific configuration methods.
package repository
import (
diff --git a/services/role/role.vdl b/services/role/role.vdl
index 454d0dc..ec5897f 100644
--- a/services/role/role.vdl
+++ b/services/role/role.vdl
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package role defines an interface for requesting blessings from a role
+// account server.
package role
import "v.io/v23/security"
diff --git a/services/role/role.vdl.go b/services/role/role.vdl.go
index 1b4ab83..a7f0ee1 100644
--- a/services/role/role.vdl.go
+++ b/services/role/role.vdl.go
@@ -5,6 +5,8 @@
// This file was auto-generated by the vanadium vdl tool.
// Source: role.vdl
+// Package role defines an interface for requesting blessings from a role
+// account server.
package role
import (
diff --git a/services/role/roled/main.go b/services/role/roled/main.go
index 655156c..5e192ad 100644
--- a/services/role/roled/main.go
+++ b/services/role/roled/main.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon roled implements the Role interface.
package main
import (
diff --git a/services/wspr/browsprd/main_nacl.go b/services/wspr/browsprd/main_nacl.go
index 7b4f7a3..a56e332 100644
--- a/services/wspr/browsprd/main_nacl.go
+++ b/services/wspr/browsprd/main_nacl.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon browsprd implements the wspr web socket proxy as a Native Client
+// executable, to be run as a Chrome extension.
package main
import (
diff --git a/services/wspr/wsprd/main.go b/services/wspr/wsprd/main.go
index bd2c1ea..c5e7068 100644
--- a/services/wspr/wsprd/main.go
+++ b/services/wspr/wsprd/main.go
@@ -2,6 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Daemon wsprd implements the wspr web socket proxy as a stand-alone server.
package main
import (
diff --git a/services/wspr/wsprlib/wspr.go b/services/wspr/wsprlib/wspr.go
index 5b87b2b..d30e5f4 100644
--- a/services/wspr/wsprlib/wspr.go
+++ b/services/wspr/wsprlib/wspr.go
@@ -2,20 +2,9 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// A simple WebSocket proxy (WSPR) that takes in a Vanadium RPC message, encoded in JSON
-// and stored in a WebSocket message, and sends it to the specified Veyron
-// endpoint.
-//
-// Input arguments must be provided as a JSON message in the following format:
-//
-// {
-// "Address" : String, //EndPoint Address
-// "Name" : String, //Service Name
-// "Method" : String, //Method Name
-// "InArgs" : { "ArgName1" : ArgVal1, "ArgName2" : ArgVal2, ... },
-// "IsStreaming" : true/false
-// }
-//
+// Package wsprlib implements utilities for the wspr web socket proxy, which
+// converts between the Vanadium RPC protocol and a custom web socket based
+// protocol.
package wsprlib
import (
diff --git a/test/benchmark/stats.go b/test/benchmark/stats.go
index f600610..fab9321 100644
--- a/test/benchmark/stats.go
+++ b/test/benchmark/stats.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package benchmark implements utilities to augment the standard Go
+// testing.Benchmark functionality.
package benchmark
import (
diff --git a/test/doc.go b/test/doc.go
index f0fbcdb..cb84f2b 100644
--- a/test/doc.go
+++ b/test/doc.go
@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package test provides initalization for unit and integration tests.
+// Package test implements initalization for unit and integration tests.
//
// Init configures logging, random number generators and other global state.
// Typical usage in _test.go files:
diff --git a/test/expect/expect.go b/test/expect/expect.go
index 9ff7e9a..1bf3932 100644
--- a/test/expect/expect.go
+++ b/test/expect/expect.go
@@ -2,13 +2,12 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package expect provides support for testing the contents from a buffered
-// input stream. It supports literal and pattern based matching. It is
+// Package expect implements support for checking expectations against a
+// buffered input stream. It supports literal and pattern based matching. It is
// line oriented; all of the methods (expect ReadAll) strip trailing newlines
-// from their return values. It places a timeout on all its operations.
-// It will generally be used to read from the stdout stream of subprocesses
-// in tests and other situations and to make 'assertions'
-// about what is to be read.
+// from their return values. It places a timeout on all its operations. It will
+// generally be used to read from the stdout stream of subprocesses in tests and
+// other situations and to make 'assertions' about what is to be read.
//
// A Session type is used to store state, in particular error state, across
// consecutive invocations of its method set. If a particular method call
diff --git a/test/modules/shell.go b/test/modules/shell.go
index 729c360..9d76804 100644
--- a/test/modules/shell.go
+++ b/test/modules/shell.go
@@ -2,13 +2,12 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package modules provides a mechanism for running commonly used services
-// as subprocesses and client functionality for accessing those services.
-// Such services and functions are collectively called 'commands' and
-// are managed by a 'Registry'. The Shell is analagous to the UNIX shell and
-// maintains a key, value store of environment variables and config settings
-// that are accessible to the commands that it hosts. Simple variable
-// expansion is supported.
+// Package modules implements a mechanism for running commonly used services as
+// subprocesses, and client functionality for accessing those services. Such
+// services and functions are collectively called 'commands' and are managed by
+// a 'Registry'. The Shell is analagous to the UNIX shell and maintains a key,
+// value store of environment variables and config settings that are accessible
+// to the commands that it hosts. Simple variable expansion is supported.
//
// Four types of 'commands' may be invoked via a Shell.
//
diff --git a/test/testutil/doc.go b/test/testutil/doc.go
index 781999c..3088a2f 100644
--- a/test/testutil/doc.go
+++ b/test/testutil/doc.go
@@ -2,6 +2,5 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package testutil provides a smorgasbord of utility functions and types for
-// unittests.
+// Package testutil implements utilities for unit and integration tests.
package testutil
diff --git a/test/timekeeper/manual_time.go b/test/timekeeper/manual_time.go
index 490ad84..afc5b36 100644
--- a/test/timekeeper/manual_time.go
+++ b/test/timekeeper/manual_time.go
@@ -2,6 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package timekeeper implements simulated time against the
+// v.io/x/ref/lib/timekeeper.TimeKeeper interface.
package timekeeper
import (
diff --git a/test/v23tests/doc.go b/test/v23tests/doc.go
index 9a6c5cd..dca518d 100644
--- a/test/v23tests/doc.go
+++ b/test/v23tests/doc.go
@@ -2,11 +2,11 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package v23tests provides support for writing end-to-end style integration
-// tests. In particular, support is provided for building binaries, running
-// processes, making assertions about their output/state and ensuring that
-// no processes or files are left behind on exit. Since such tests are often
-// difficult to debug facilities are provided to help do so.
+// Package v23tests implements support for writing writing end-to-end
+// integration tests. In particular, support is provided for building binaries,
+// running processes, making assertions about their output/state and ensuring
+// that no processes or files are left behind on exit. Since such tests are
+// often difficult to debug facilities are provided to help do so.
//
// The preferred usage of this integration test framework is via the v23
// tool which generates supporting code. The primary reason for doing so is
