Format comments for documentation generator (#6)

src/components/GameBoard.component.js

@@ -39,7 +39,12 @@ const template  = `
     </div>
 </div>
 `
-export default class GameBoardComponent extends Component {
+
+/**
+ * A component which represents a single, programmable game board.
+ * @extends Component
+ */
+class GameBoardComponent extends Component {
     static get selector() { return 'app-game-board' }
     static get template() { return template }
     static get props() { return ['rows', 'is_placement_mode', 'ships_to_place', 'is_missile_mode'] }
@@ -60,7 +65,7 @@ export default class GameBoardComponent extends Component {
     /**
      * Array of coordinates as [row_index, column_index] of cells which should
      * show a ghost ship overlay.
-     * @type {[number, number][]}
+     * @type {number[]}
      */
     ship_ghost_cells = []
 
@@ -83,6 +88,10 @@ export default class GameBoardComponent extends Component {
      */
     bound_fns = []
 
+    /**
+     * Called when the component is initialized.
+     * @return {Promise<void>}
+     */
     async vue_on_create() {
         this.ready = true
 
@@ -96,6 +105,10 @@ export default class GameBoardComponent extends Component {
         window.addEventListener('keydown', keydown_fn)
     }
 
+    /**
+     * Called when the component is destroyed.
+     * @return {Promise<void>}
+     */
     async vue_on_destroy() {
         // Remove the event listeners for the shift key
         const [keyup_fn, keydown_fn] = this.bound_fns
@@ -103,6 +116,12 @@ export default class GameBoardComponent extends Component {
         window.removeEventListener('keydown', keydown_fn)
     }
 
+    /**
+     * Called when a user clicks a cell. If in placement mode, will attempt to place
+     * a ship. If in missile mode, will attempt to fire a missile.
+     * @param {number} row_i - the index of the row
+     * @param {number} cell_i - the index of the cell
+     */
     on_cell_click(row_i, cell_i) {
         if ( this.is_placement_mode && this.ships_to_place[0] ) {
             // We should try to place a ship here
@@ -213,3 +232,5 @@ export default class GameBoardComponent extends Component {
         }
     }
 }
+
+export default GameBoardComponent

src/components/GridCell.component.js

@@ -14,7 +14,12 @@ const template = `
 
 </div>
 `
-export default class GridCellComponent extends Component {
+
+/**
+ * A component which represents a single, programmable grid cell.
+ * @extends Component
+ */
+class GridCellComponent extends Component {
     static get selector() { return 'app-game-cell' }
     static get template() { return template }
 
@@ -29,15 +34,27 @@ export default class GridCellComponent extends Component {
     /** Make the "GridCellState" enum available in the template. */
     GridCellState = GridCellState
 
+    /**
+     * Fire a click event.
+     */
     on_click() {
         this.$emit('click')
     }
 
+    /**
+     * Fire a hover event.
+     * @param $event
+     */
     on_hover($event) {
         this.$emit('hover', $event)
     }
 
+    /**
+     * Fire a "hoverchange" event.
+     */
     on_mouse_leave() {
         this.$emit('hoverchange')
     }
 }
+
+export default GridCellComponent

src/components/ScoreBoard.component.js

@@ -27,20 +27,58 @@ const template = `
     </table>
 </div>
 `
-export default class ScoreBoardComponent extends Component {
+
+/**
+ * A component which represents the programmable scoreboard.
+ * @extends Component
+ */
+class ScoreBoardComponent extends Component {
     static get selector() { return 'app-scoreboard' }
     static get template() { return template }
     static get props() { return [] }
 
+    /**
+     * The score of player one.
+     * @type {number}
+     */
     player_one_score = 0
+
+    /**
+     * The score of player two.
+     * @type {number}
+     */
     player_two_score = 0
+
+    /**
+     * The progress of player one, as a decimal.
+     * @type {number}
+     */
     player_one_progress = 0
+
+    /**
+     * The progress of player two, as a decimal.
+     * @type {number}
+     */
     player_two_progress = 0
+
+    /**
+     * The current player.
+     * @type {string|undefined}
+     */
     current_player = undefined
+
+    /**
+     * The winning player.
+     * @type {string|undefined}
+     */
     winning_player = undefined
 
     Player = Player
 
+    /**
+     * Called when the component is initialized.
+     * @return {Promise<void>}
+     */
     async vue_on_create() {
         game_service.on_state_change(() => {
             this.update()
@@ -49,6 +87,9 @@ export default class ScoreBoardComponent extends Component {
         this.update()
     }
 
+    /**
+     * Fetch new data from the game service.
+     */
     update() {
         // here is where you should fetch the data from the game service and update variables on the class
         this.player_one_score = game_service.get_player_score(Player.One)
@@ -64,3 +105,5 @@ export default class ScoreBoardComponent extends Component {
         }
     }
 }
+
+export default ScoreBoardComponent

src/components/TopLevel.component.js

@@ -80,7 +80,12 @@ const template = `
     </div>
 </div>
 `
-export default class TopLevelComponent extends Component {
+
+/**
+ * Top-level component which manages the display of the entire game.
+ * @extends Component
+ */
+class TopLevelComponent extends Component {
     static get selector() { return 'app-top-level' }
     static get template() { return template }
     static get props() { return [] }
@@ -145,8 +150,11 @@ export default class TopLevelComponent extends Component {
      */
     current_opponent_display = ''
 
+    /**
+     * Called when the component is initialized.
+     * @return {Promise<void>}
+     */
     async vue_on_create() {
-        console.log('game service', game_service)
         this.current_state = game_service.get_game_state()
 
         // Called every time the game state is updated
@@ -220,3 +228,5 @@ export default class TopLevelComponent extends Component {
         game_service.advance_game_state()
     }
 }
+
+export default TopLevelComponent

src/module/errors.js

@@ -1,3 +1,5 @@
+/** @module errors */
+
 /**
  * Placeholder class for an error that is thrown when a ship is placed
  * in an invalid position.

src/module/lang.js

@@ -1,3 +1,5 @@
+/** @module lang **/
+
 import { GameState } from './util.js'
 
 /**

src/module/sounds.js

@@ -1,3 +1,5 @@
+/** @module sounds */
+
 import { appUrl } from './util.js'
 
 /**
@@ -42,6 +44,10 @@ class Sound {
     }
 }
 
+/**
+ * Enum of the various sound effects available in the game.
+ * @type {object}
+ */
 const GameSounds = {
     Victory: new Sound(appUrl('/lib/sounds/cartoon_success_fanfair.mp3')),
     Fire: new Sound(appUrl('/lib/sounds/zapsplat_warfare_mortar_projectile_launch_002_25232.mp3')),
@@ -49,6 +55,4 @@ const GameSounds = {
     Miss: new Sound(appUrl('/lib/sounds/zapsplat_nature_water_pour_medium_amount_deep_sudden_fast_002_52765.mp3')),
 }
 
-console.log(GameSounds)
-
 export { GameSounds }

src/module/util.js

@@ -1,3 +1,5 @@
+/** @module util */
+
 /**
  * Enum of all possible states of a grid cell.
  * @type {object}

src/services/GameState.service.js

@@ -22,7 +22,7 @@ export class GameStateService {
     /**
      * An array of all players. This is mostly for internal purposes.
      * @private
-     * @type {(string)[]}
+     * @type {string[]}
      */
     players = [Player.One, Player.Two]
 
@@ -71,7 +71,7 @@ export class GameStateService {
     /**
      * Given the number of boats set by the player (n_boats), return an array
      * of possible ShipTypes.
-     * @return {ShipType[]}
+     * @return {string[]}
      */
     get_possible_boats(){
         if (this.get_n_boats() === 1) {
@@ -115,7 +115,7 @@ export class GameStateService {
     /**
      * If the current state is the PromptPlayerChange, then this is
      * the state that we should move to next.
-     * @type {undefined|GameState}
+     * @type {undefined|string}
      */
     post_player_change_state = undefined
 
@@ -145,7 +145,7 @@ export class GameStateService {
     /**
      * Get the dimensions of the board as [rows, cols].
      * @example const [n_rows, n_cols] = game_service.get_dimensions()
-     * @return {[number, number]}
+     * @return {number[]}
      */
     get_dimensions() {
         return [this.n_rows, this.n_cols]
@@ -266,7 +266,7 @@ export class GameStateService {
 
     /**
      * Get the current game state.
-     * @return {GameState}
+     * @return {string}
      */
     get_game_state() {
         return clone(this.current_state)
@@ -275,7 +275,6 @@ export class GameStateService {
     /**
      * responsible for advancing the game state
      * will be consisting of
-     * @return
      */
     advance_game_state() {
         /** functions to be made that validate:
@@ -383,7 +382,7 @@ export class GameStateService {
      * If I want to fire a missile at row 5 column 7, then:
      * game_service.attempt_missile_fire([5, 7])
      *
-     * @param {[number, number]} coords
+     * @param {number[]} coords
      * @return {boolean}
      */
     attempt_missile_fire([target_row_i, target_col_i]) {
@@ -419,7 +418,7 @@ export class GameStateService {
     /**
      * Checks the player's ships. If any are fully damaged, it flags that ship's cells
      * as "sunk" rather than damaged.
-     * @param {Player} player
+     * @param {string} player
      * @private
      */
     _sink_damaged_ships(player) {
@@ -448,9 +447,9 @@ export class GameStateService {
      * to row 3 column 4, then I would call:
      * game_service.place_ship(ShipType.x3, [3,2], [3,4])
      *
-     * @param {ShipType} ship_type
+     * @param {string} ship_type
-     * @param {[number, number]} coords_one
+     * @param {number[]} coords_one
-     * @param {[number, number]} coords_two
+     * @param {number[]} coords_two
      */
     place_ship(ship_type, coords_one, coords_two) {
         // make sure the coordinates are valid for the given ship type
@@ -490,9 +489,9 @@ export class GameStateService {
      * game_service.get_covered_cells([1,1], [4,1])
      * Which would return [[1,1], [2,1], [3,1], [4,1]].
      *
-     * @param {[number, number]} coords_one
+     * @param {number[]} coords_one
-     * @param {[number, number]} coords_two
+     * @param {number[]} coords_two
-     * @return {[number, number][]}
+     * @return {number[][]}
      */
     get_covered_cells(coords_one, coords_two) {
         const [row_one, col_one] = coords_one
@@ -522,9 +521,9 @@ export class GameStateService {
      * to row 3 column 4, then I would call:
      * game_service.validate_coordinates(ShipType.x3, [3,2], [3,4])
      *
-     * @param {ShipType} ship_type
+     * @param {string} ship_type
-     * @param {[number, number]} coords_one
+     * @param {number[]} coords_one
-     * @param {[number, number]} coords_two
+     * @param {number[]} coords_two
      */
     validate_coordinates(ship_type, coords_one, coords_two) {
         if ( !isShipType(ship_type) ) throw new InvalidShipPlacementError('Invalid ship type: '+ship_type)
@@ -570,7 +569,7 @@ export class GameStateService {
 
     /**
      * Get the number of cells the given ship type should occupy.
-     * @param {ShipType} ship_type
+     * @param {string} ship_type
      * @return {number}
      */
     get_ship_length(ship_type) {
@@ -583,8 +582,8 @@ export class GameStateService {
 
     /**
      * Get the coordinates of all cells that have ships in them, for the given player.
-     * @param {Player} player
+     * @param {string} player
-     * @return {[number, number]}
+     * @return {number[]}
      */
     get_ship_cells(player) {
         const cells = []
@@ -601,7 +600,7 @@ export class GameStateService {
     /**
      * If there is a winner, this will return the Player that won.
      * If no winner has been decided yet, will return undefined.
-     * @return {Player|undefined}
+     * @return {string|undefined}
      */
     get_winner() {
         const [player_1, player_2] = this.players
@@ -627,8 +626,8 @@ export class GameStateService {
 
     /**
      * Returns the other player.
-     * @param {Player} player
+     * @param {string} player
-     * @return {Player}
+     * @return {string}
      */
     get_other_player(player) {
         if ( player === Player.One ) return Player.Two
@@ -637,7 +636,7 @@ export class GameStateService {
 
     /**
      * Given a Player type, return the display value of that player.
-     * @param {Player} player
+     * @param {string} player
      * @return {string}
      */
     get_player_display(player) {
@@ -647,7 +646,7 @@ export class GameStateService {
 
     /**
      * Get an array of ship entities for the given player.
-     * @param {Player} player
+     * @param {string} player
      * @return {object[]}
      */
     get_ship_entities(player) {
@@ -672,10 +671,10 @@ export class GameStateService {
     /**
      * Set the state of the cell at the given coordinates on the player's board
      * to the specified state.
-     * @param {Player} player
+     * @param {string} player
      * @param {number} row_i
      * @param {number} col_i
-     * @param {GridCellState} state
+     * @param {string} state
      * @private
      */
     _set_cell_state(player, row_i, col_i, state) {
@@ -684,7 +683,7 @@ export class GameStateService {
 
     /**
      * Get the state of the cell at the given coordinates on the player's board.
-     * @param {Player} player
+     * @param {string} player
      * @param {number} row_i
      * @param {number} col_i
      * @return {object}