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/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 (
