ABI Documentation

ABI documentation refers to documenting the interface that another developer may be interested in using.

The form of documentation we focus on uses the /// syntax as we are interested in documenting the ABI functions.

In the following snippet, we provide a short description about the functions, the arguments they take, and when the calls will revert. Additional data may be added such as the structure of the return type, how to call the function, etc.

library;

use ::data_structures::{Game, Player};

abi ConnectFour {
    /// Creates a new game
    ///
    /// Creating a game allows players to sequentially take turns placing their marker in an empty
    /// spot until a player reaches four in a row or the board is filled and a draw is declared
    ///
    /// # Arguments
    ///
    /// - `player_one` - The first player to make a move
    /// - `player_two` - The second player to make a move
    ///
    /// # Reverts
    ///
    /// - When a player has been blacklisted for cheating
    fn create_game(player_one: Player, player_two: Player) -> Game;

    /// Places a marker from the next player in the game in the specified column
    ///
    /// # Arguments
    ///
    /// - `column` - The column to place a marker in, range 0 <= column < 8
    /// - `game` - The game to make a move in
    ///
    /// # Reverts
    ///
    /// - When a game has ended in a player winning or a draw
    /// - When a marker is placed into a `column` that is full
    fn move(column: u64, game: Game) -> Game;
}

In order to know what should be documented, the author of the code should put themselves in the position of a developer that knows nothing about the function and think about what sort of questions they may have.