examples: cleanup to make godoc look better
This CL adds package-level comments to packages that had none and for
brevity, conflates several "impl", "lib", or "schema" packages with
their sole consumer.
Let's use this CL to develop the conventions to apply across all of
our other Go repositories.
Change-Id: I6ba6f5fcb643270082b029c933df0a9c9994a213
diff --git a/service.vdl b/service.vdl
new file mode 100644
index 0000000..07911d9
--- /dev/null
+++ b/service.vdl
@@ -0,0 +1,104 @@
+// Package rps is an example of veyron service for playing the game of
+// Rock-Paper-Scissors. (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.
+//
+// 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.
+package rps
+
+type RockPaperScissors interface {
+ Judge
+ Player
+ ScoreKeeper
+}
+
+type Judge interface {
+ // CreateGame creates a new game with the given game options and returns a game
+ // identifier that can be used by the players to join the game.
+ CreateGame(Opts GameOptions) (GameID, error)
+ // Play lets a player join an existing game and play.
+ Play(ID GameID) stream<PlayerAction,JudgeAction> (PlayResult, error)
+}
+
+// A GameID is used to uniquely identify a game within one Judge.
+type GameID struct {
+ ID string
+}
+
+// GameOptions specifies the parameters of a game.
+type GameOptions struct {
+ NumRounds int32 // The number of rounds that a player must win to win the game.
+ GameType GameTypeTag // The type of game to play: Classic or LizardSpock.
+}
+
+type GameTypeTag byte
+const (
+ Classic = GameTypeTag(0) // Rock-Paper-Scissors
+ LizardSpock = GameTypeTag(1) // Rock-Paper-Scissors-Lizard-Spock
+)
+
+type PlayerAction struct {
+ Move string // The move that the player wants to make.
+ Quit bool // Whether the player wants to quit the game.
+}
+
+type JudgeAction struct {
+ PlayerNum int32 // The player's number.
+ OpponentName string // The name of the opponent.
+ MoveOptions []string // A list of allowed moves that the player must choose from. Not always present.
+ RoundResult Round // The result of the previous round. Not always present.
+ Score ScoreCard // The result of the game. Not always present.
+}
+
+// Round represents the state of a round.
+type Round struct {
+ Moves [2]string // Each player's move.
+ Comment string // A text comment from judge about the round.
+ Winner WinnerTag // Who won the round.
+ StartTimeNS int64 // The time at which the round started.
+ EndTimeNS int64 // The time at which the round ended.
+}
+
+// WinnerTag is a type used to indicate whether a round or a game was a draw,
+// was won by player 1 or was won by player 2.
+type WinnerTag byte
+const (
+ Draw = WinnerTag(0)
+ Player1 = WinnerTag(1)
+ Player2 = WinnerTag(2)
+)
+
+// PlayResult is the value returned by the Play method. It indicates the outcome of the game.
+type PlayResult struct {
+ YouWon bool // True if the player receiving the result won the game.
+}
+
+// Player can receive challenges from other players.
+type Player interface {
+ // Challenge is used by other players to challenge this player to a game. If
+ // the challenge is accepted, the method returns nil.
+ Challenge(Address string, ID GameID, Opts GameOptions) error
+}
+
+// ScoreKeeper receives the outcome of games from Judges.
+type ScoreKeeper interface {
+ Record(Score ScoreCard) error
+}
+
+type ScoreCard struct {
+ Opts GameOptions // The game options.
+ Judge string // The name of the judge.
+ Players []string // The name of the players.
+ Rounds []Round // The outcome of each round.
+ StartTimeNS int64 // The time at which the game started.
+ EndTimeNS int64 // The time at which the game ended.
+ Winner WinnerTag // Who won the game.
+}
