Adds docs for all exported methods.

api/api.go

@@ -2,8 +2,10 @@ package api
 
 import "errors"
 
+// API represents the cheesse API. All cheesse API methods are exported methods of this struct.
 type API struct{}
 
+// New constructs an API.
 func New() API { return API{} }
 
 var (
@@ -13,11 +15,20 @@ var (
 	errInvalidActionForGivenGame           = errors.New("the specified action is invalid for the specified game")
 )
 
+// DefaultGame returns the initial game of chess, with all pieces on their default positions
+// and before any action has taken place.
 func (a API) DefaultGame() OutputGame {
 	var defaultGame, _ = newGameFromFEN("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
 	return mapGameToOutputGame(defaultGame)
 }
 
+// ParseGame takes any valid input game and parses it, returning an OutputGame, which contains
+// a lot of useful information about it, like possible actions, locations of pieces, game state
+// in terms of threats, is the game over, etc.
+//
+// If the input game is invalid, an error will be returned with a description of the problem.
+//
+// Please refer to InputGame's and OutputGame's docs for format details.
 func (a API) ParseGame(game InputGame) (OutputGame, error) {
 	parsedGame, err := a.parseGame(game)
 	if err != nil {
@@ -26,6 +37,15 @@ func (a API) ParseGame(game InputGame) (OutputGame, error) {
 	return mapGameToOutputGame(parsedGame), nil
 }
 
+// DoAction takes any valid input game and any valid input action, parses them and attempts
+// to apply the action on the given game. If parsing any of the entities fails or applying
+// the action on the parsed game fails an error will be returned.
+//
+// If applying the action succeeds, it returns the parsed action and the resulting game
+// AFTER applying the action.
+//
+// Please refer to InputGame's, InputAction's, OutputGame's and OutputAction's docs for
+// format details.
 func (a API) DoAction(game InputGame, action InputAction) (OutputGame, OutputAction, error) {
 	parsedGame, err := a.parseGame(game)
 	if err != nil {
@@ -38,6 +58,22 @@ func (a API) DoAction(game InputGame, action InputAction) (OutputGame, OutputAct
 	return mapGameToOutputGame(parsedGame.doAction(parsedAction)), mapInternalActionToAction(parsedAction), nil
 }
 
+// ParseNotation takes any valid input game and a string representing a match in some
+// notation, parses them and attempts to play the match starting from the supplied
+// game. If it fails, it returns an error describing the problem.
+//
+// If parsing the match succeeds, it returns the parsed initial game and a list of
+// steps, one per action in the `notationString`.
+//
+// An example `notationString` (Scholar's mate):
+//
+// `1. e4 e5\n2. Bc4 Nc6\n3. Qh5 Nf6??\n4. Qxf7#`
+//
+// At the moment, only Algebraic Notation is supported, but support for most
+// notations is planned at a later release.
+//
+// Please refer to InputGame's, OutputGame's and OutputGameStep's docs for format
+// details.
 func (a API) ParseNotation(game InputGame, notationString string) (OutputGame, []OutputGameStep, error) {
 	parsedGame, err := a.parseGame(game)
 	if err != nil {

api/api_entities.go

@@ -1,16 +1,49 @@
 package api
 
+// InputGame is the input interface to supply a chess game.
+//
+// There are 3 different ways to supply the chess game:
+//
+// 1. via `fenString`: supply a FEN Notation string.
+//
+// 2. via `board`: supply the board, together with required aspects of the game state.
+//
+// 3. via empty struct: assumes the defaultGame.
+//
+// If you supply both the `fenString` and the `board`, `board` is ignored silently.
 type InputGame struct {
 	FENString string `json:"fenString"`
 	Board     Board  `json:"board"`
 }
 
+// InputAction is the input interface to supply a chess action.
+//
+// - `fromSquare` and `toSquare` are required, and must be board cells described in
+// Algebraic Notation (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts.
+//
+// - `promotionPieceType` is only required if the action is a promotion.
+//
+// - `promotionPieceType` must be one of: `{Queen|King|Bishop|Knight|Rook|Pawn}`.
 type InputAction struct {
 	FromSquare         string `json:"fromSquare"`
 	ToSquare           string `json:"toSquare"`
 	PromotionPieceType string `json:"promotionPieceType"`
 }
 
+// Board is one of the input interfaces to supply a chess game.
+//
+// The `board` struct member must consist of 8 strings of length 8, containing the
+// representation of the chess board using unicode characters. For the empty cells,
+// any character may be used, but the output board will use spaces.
+//
+// The other struct members represent all required game state as described in the
+// FEN notation.
+//
+// - `enPassantTargetSquare` must be a board cell described in Algebraic Notation
+// (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts. If there's
+// no en passant target square, it must be an empty string.
+//
+// - `turn` must be one of: `{Black|White}`.
 type Board struct {
 	Board                   []string `json:"board"`
 	CanWhiteKingsideCastle  bool     `json:"canWhiteKingsideCastle"`
@@ -23,6 +56,34 @@ type Board struct {
 	Turn                    string   `json:"turn"`                  // "Black" or "White"
 }
 
+// OutputGame is the output interface that describes a chess game.
+// All API calls that return a chess game represent it with an OutputGame.
+//
+// - `fenString` represents the chess game as a FEN Notation string.
+//
+// - `actions` is the exhaustive list of actions that can follow from this game.
+//
+// - `enPassantTargetSquare` is a board cell described in Algebraic Notation
+// (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts. If there's
+// no en passant target square, it's an empty string.
+//
+// - `blackPieces` and `whitePieces` are maps from cells to piece names. The cells
+// are represented in Algebraic Notation (e.g `e2`), and the piece names are one
+// of `{Queen|King|Bishop|Knight|Rook|Pawn}`.
+//
+// - `blackKing` and `whiteKing` are the cells where the Kings are located. The
+// cells are represented in Algebraic Notation (e.g `e2`).
+//
+// - `gameOverWinner` is one of `{Black|White|Unknown}`, and represents the winner
+// of the game, when `isGameOver` is true. `Unknown` otherwise.
+//
+// - `inCheckBy` is a list of cells whose pieces are threatening the player whose
+// turn it is to move. `board.turn` dictates who this player is. The cells are
+// represented in Algebraic Notation (e.g `e2`). To find out which piece is in a
+// cell, inspect `blackPieces` and `whitePieces`.
+//
+// Because OutputGame is a superset of InputGame, you may supply an OutputGame to
+// any API call that expects an InputGame.
 type OutputGame struct {
 	FENString               string            `json:"fenString"`
 	Board                   Board             `json:"board"`
@@ -51,6 +112,25 @@ type OutputGame struct {
 	InCheckBy               []string          `json:"inCheckBy"`
 }
 
+// OutputAction is the output interface that describes a chess action.
+// All API calls that return a chess action represent it with an OutputAction.
+//
+// - `fromPieceOwner` is one of `{Black|White}`. The owner of the piece doing
+// the action.
+//
+// - `fromPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`.
+//
+// - `fromPieceSquare` and `toSquare` are the source and destination board
+// cells for the action, described in Algebraic Notation (e.g. `e2`). Note
+// that `a1` is where the White Queen's Rook starts.
+//
+// - `promotionPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`,
+// and represents the piece that a Pawn promotes to, if the action is a
+// promotion. If the action is not a promotion, it's an empty string.
+//
+// - `capturedPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`,
+// and represents the piece that was captured, if the action is a capture.
+// If the action is not a capture, it's an empty string.
 type OutputAction struct {
 	FromPieceOwner     string `json:"fromPieceOwner"`
 	FromPieceType      string `json:"fromPieceType"`
@@ -68,6 +148,23 @@ type OutputAction struct {
 	CapturedPieceType  string `json:"capturedPieceType"`
 }
 
+// OutputGameStep is the output interface that describes a step in a parsed
+// or converted match in a given notation string.
+//
+// A given notation string is parsed into a list of "action strings", each
+// one representing each action in the match. There will be an OutputGameStep
+// for each one of these "action strings".
+//
+// Please refer to the docs for the OutputGame and OutputAction formats.
+//
+// -  `actionString` is a string representing a chess action as supplied by the
+// client, so it could be in any of the supported notations, and is not
+// modified by the API. It could be incorrectly sliced, though.
+//
+// - `action` represents the action that the API inferred from the
+// `actionString`.
+//
+// - `game` represents the chess game AFTER applying the inferred action.
 type OutputGameStep struct {
 	Game         OutputGame   `json:"game"`
 	Action       OutputAction `json:"action"`