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