Merge pull request #199 from oskarrough/chore/jsdocs

More comments and types

DOCUMENTATION.md

@@ -2,15 +2,16 @@
 
 Throughout the project I've attempted to document and leave comments. So please, go ahead and explore all folders and files. In the root of this project you'll find configuration files as well as two folders:
 
-- [src →](src/) The web root, ready to deploy to any static web server. No compilation required. You can open the folder locally with your browser, or if you want livereload, with `npm start`.
+- [src →](src/) The web root. All code is transpiled.
   - [game](src/game) contains the core game logic
   - [content](src/content) uses methods from the game engine to build cards, dungeon and monsters
   - [ui](src/ui) is the example web interface to actually play the game
+- [public →](public/) Copied to the web root as-is
 - [tests →](tests/) Contains all tests for the game engine. Nothing for the UI. Run `npm test`.
 
-## Public
+## Src
 
-This is the full source code of the game _and_ UI. The folder is meant to be deployed as-is to any static web server. The game logic does not concern with the UI.
+This is the full source code of the game _and_ UI. The game logic does not concern with the UI.
 
 ### Game
 

README.md

@@ -14,7 +14,7 @@ After many runs in the Spire, I really got into the theory behind the game. Insp
 
 If you're interested in contributing to the game or merely curious how it works, see [the documentation](DOCUMENTATION.md).
 
-TLDR; Clone the repository and run `npm install` followed by `npm start` to open a local development server. The `src/game` folder contains the actual game logic and the `src/ui` folder is the website UI where you can actually play the game. 
+TLDR; Clone the repository and run `npm install` followed by `npm run dev` to open a local development server. The `src/game` folder contains the actual game logic and the `src/ui` folder is the website UI where you can actually play the game. 
 
 ## How to deploy it
 

jsconfig.json

@@ -1,6 +1,7 @@
 {
 	"compilerOptions": {
 		"checkJs": true,
+		"allowJs": true,
 		"target": "esnext",
 		"moduleResolution": "nodenext"
 	},

src/content/cards.js

@@ -1,6 +1,5 @@
 // Here you'll find all the default cards used in the game.
 // See game/cards.js for the details on how they work.
-
 export default [
 	{
 		name: 'Strike',

src/game/action-manager.js

@@ -1,37 +1,64 @@
 import Queue from './queue.js'
 import actions from './actions.js'
 
-// The action manager makes use of queues to keep track of
-// future and past actions in the game state. Also allowing us to undo.
+/**
+ * @typedef {Object} FutureAction
+ * @prop {string} type - the name of a function in actions.js
+ * @prop {any} [any] - arguments are passed to the action
+ */
+
+/**
+ * @typedef {Object} PastAction
+ * @prop {string} type - the name of a function in actions.js
+ * @prop {import('./actions.js').State} state
+ */
+
+/**
+ * The action manager makes use of queues to keep track of future and past actions in the game state + undo.
+ * @param {Object} props
+ * @prop {boolean} props.debug - whether to log actions to the console
+ */
 export default function ActionManager(props) {
 	const future = new Queue()
 	const past = new Queue()
 
-	// Enqueued items are added to the "future" list. An action looks like this:
-	// {type: 'dealDamage', amount: 7, ... }
+	/**
+	 * Enqueued items are added to the "future" list
+	 * @param {FutureAction} action
+	 */
 	function enqueue(action) {
 		if (props.debug) console.log('am:enqueue', action)
 		future.enqueue({action})
 	}
 
-	// Deqeueing means running the oldest action in the queue on a game state.
-	// The action is then moved to the "past". Returns the next state.
+	/**
+	 * Deqeueing runs the oldest action (from the `future` queue) on the state.
+	 * The action is then moved to the `past` queue.
+	 * @param {import('./actions.js').State} state
+	 * @returns {import('./actions.js').State} new state
+	 */
 	function dequeue(state) {
+		// Get the oldest action
 		const {action} = future.dequeue() || {}
 		if (props.debug) console.log('am:dequeue', action)
+		if (!action) return state
+		// Run it on the state
 		let nextState
-		if (!action) return
 		try {
 			nextState = actions[action.type](state, action)
 		} catch (err) {
 			console.warn('am:Failed running action', action)
 			throw new Error(err)
 		}
-		past.enqueue({state, action})
+		// Move the action along with its state to the past
+		past.enqueue({action, state})
 		return nextState
 	}
 
-	// Returns an object with the most recently run action and how the state looked before.
+	/**
+	 * Returns an object with the most recently run action and how the state looked before.
+	 * @returns {PastAction}
+	 */
 	function undo() {
 		if (props.debug) console.log('am:undo')
 		return this.past.list.pop()