# HG changeset patch # User Oleksandr Gavenko # Date 1410738542 -10800 # Node ID 94e1b2d0bd311408ec2f5685141e69b8efde9854 # Parent 76d257640b7da06f057114690be6f7c86f821f9e Add JSDoc annotation. diff -r 76d257640b7d -r 94e1b2d0bd31 Makefile --- a/Makefile Thu Sep 11 20:01:40 2014 +0300 +++ b/Makefile Mon Sep 15 02:49:02 2014 +0300 @@ -88,12 +88,16 @@ DIST_DIR = $(fullpkgname) -WWW_FILES := $(wildcard *.js) $(wildcard *.html) +JS_FILES := $(wildcard *.js) +HTML_FILES := $(wildcard *.html) +WWW_FILES := $(JS_FILES) $(HTML_FILES) DIST_FILES = $(WWW_FILES) README.rst VERSION DIST_TARBALLS = $(DIST_DIR).tar.gz $(DIST_DIR).zip +JSDOC_DIR := jsdoc + ################################################################ # Deploy targets. @@ -199,6 +203,10 @@ echo; \ sed -n -e '/^[[:alnum:]_-]*:/{s=^\(.*\):.*= \1=;p;}' $(BUILD_SCRIPTS) +.PHONY: jsdoc +jsdoc: + jsdoc -a -p -d=$(JSDOC_DIR) $(JS_FILES) + ################################################################ # Clean targets. @@ -208,4 +216,5 @@ .PHONY: clean clean: - rm -rf $(DIST_DIR) $(DIST_TARBALLS) + rm -rf $(JSDOC_DIR) $(DIST_DIR) $(DIST_TARBALLS) + diff -r 76d257640b7d -r 94e1b2d0bd31 README.rst --- a/README.rst Thu Sep 11 20:01:40 2014 +0300 +++ b/README.rst Mon Sep 15 02:49:02 2014 +0300 @@ -3,3 +3,16 @@ 2048 game JS AI. ================== +Build jsdoc. +============ + +.. code:: console + + $ make jsdoc + +Refer for JSDoc syntax to: + + * http://usejsdoc.org/ + * https://developers.google.com/closure/compiler/docs/js-for-compiler + * https://code.google.com/p/jsdoc-toolkit/w/list + diff -r 76d257640b7d -r 94e1b2d0bd31 ai.js --- a/ai.js Thu Sep 11 20:01:40 2014 +0300 +++ b/ai.js Mon Sep 15 02:49:02 2014 +0300 @@ -1,10 +1,15 @@ "use strict"; +/** @fileOverview AI modules. */ + +/** @module */ var ai = {}; +/** Directions. @constant */ ai.dirs = ["up", "right", "down", "left"]; +/** Possible direction function names. @constant */ ai.canDirs = ["canUp", "canRight", "canDown", "canLeft"]; -/* Create empty 'to' if argument missing. */ +/** Create empty 'to' if argument missing. */ ai.copyObj = function(from, to) { if (to == null || typeof to !== "object") to = {}; @@ -26,6 +31,9 @@ // Blind random AI. //////////////////////////////////////////////////////////////// +/** Blind random AI. + * @param {Board} brdEngine board engine from board.js + * @constructor */ ai.blindRandom = function(brdEngine) { this.brdEngine = brdEngine; } @@ -46,6 +54,19 @@ // Blind weight random AI. //////////////////////////////////////////////////////////////// +/** + * @name ai.BlindWeightRandom.cfg + * @namespace + * @property {number} left weight + * @property {number} right weight + * @property {number} up weight + * @property {number} down weight + */ + +/** Blind weight random AI. + * @param {Board} brdEngine board engine from board.js + * @param {ai.BlindWeightRandom.cfg} cfg configuration settings + * @constructor */ ai.blindWeightRandom = function(brdEngine, cfg) { this.brdEngine = brdEngine; this.cfg = ai.copyObj(ai.blindWeightRandom.bestCfg); @@ -55,7 +76,9 @@ this.threshold2 = (this.cfg.left + this.cfg.down)/total; this.threshold3 = (this.cfg.left + this.cfg.down + this.cfg.right)/total; } -ai.blindWeightRandom.bestCfg = {left: 1, down: 10, right: 5, up: 1}; +/** @{link ai.BlindWeightRandom.cfg} + @namespace */ +ai.blindWeightRandom.bestCfg = { left: 1, down: 10, right: 5, up: 1 }; ai.blindWeightRandom.prototype.analyse = function(brd) { var origBrd = new this.brdEngine(brd); while (true) { @@ -81,6 +104,17 @@ // Blind cycle AI. //////////////////////////////////////////////////////////////// +/** + * @name ai.BlindCycle.cfg + * @namespace + * @property {boolean} whilePossible move in one direction while possible + * @property {boolean} down switch direction clockwise + */ + +/** Blind cycle AI. + * @param {Board} brdEngine board engine from board.js + * @param {ai.BlindCycle.cfg} cfg configuration settings + * @constructor */ ai.blindCycle = function(brdEngine, cfg) { this.brdEngine = brdEngine; this.cfg = cfg || {}; @@ -119,6 +153,21 @@ // for each free field. //////////////////////////////////////////////////////////////// +/** + * Defines coefficient for linear resulted weight function. + * @name ai.OneStepDeep.cfg + * @namespace + * @property {number} scoreCoef multiplicator for score + * @property {number} maxValCoef multiplicator for max value + * @property {number} cornerBonus bonus for max value at board corner + * @property {number} edgeBonus bonus for max value at board edge + * @property {number} freeBonus bonus foe each free cell + */ + +/** 1 step deep with * AI. + * @param {Board} brdEngine board engine from board.js + * @param {ai.OneStepDeep.cfg} cfg configuration settings + * @constructor */ ai.oneStepDeep = function(brdEngine, cfg) { this.brdEngine = brdEngine; this.cfg = ai.copyObj(ai.oneStepDeep.bestCfg); @@ -166,6 +215,9 @@ // N level deep on score value without random simulation. //////////////////////////////////////////////////////////////// +/** N level deep on score value without random simulation. + * @param {Board} brdEngine board engine from board.js + * @constructor */ ai.deepMaxScore = function(brdEngine) { this.brdEngine = brdEngine; } @@ -221,8 +273,21 @@ // without random simulation. //////////////////////////////////////////////////////////////// -/* cfg.cornerBonus - value to add if max value at corner. */ -/* cfg.edgeBonus - value to add if max value at edge. */ +/** + * Defines coefficient for linear resulted weight function. + * @name ai.DeepMaxScoreCorner.cfg + * @namespace + * @property {number} scoreCoef multiplicator for score + * @property {number} maxValCoef multiplicator for max value + * @property {number} cornerBonus bonus for max value at board corner + * @property {number} edgeBonus bonus for max value at board edge + * @property {number} freeBonus bonus foe each free cell + */ + +/** N level deep AI without random simulation. + * @param {Board} brdEngine board engine from board.js + * @param {Object} cfg configuration settings + * @constructor */ ai.deepMaxScoreCorner = function(brdEngine, cfg) { this.brdEngine = brdEngine; this.cfg = cfg || {}; @@ -298,8 +363,21 @@ // N level deep with random simulation. //////////////////////////////////////////////////////////////// -/* cfg.cornerBonus - value to add if max value at corner. */ -/* cfg.edgeBonus - value to add if max value at edge. */ +/** + * Defines coefficient for linear resulted weight function. + * @name ai.expectimax.cfg + * @namespace + * @property {number} scoreCoef multiplicator for score + * @property {number} maxValCoef multiplicator for max value + * @property {number} cornerBonus bonus for max value at board corner + * @property {number} edgeBonus bonus for max value at board edge + * @property {number} freeBonus bonus foe each free cell + */ + +/** N level deep with random simulation. + * @param {Board} brdEngine board engine from board.js + * @param {ai.expectimax.cfg} cfg configuration settings + * @constructor */ ai.expectimax = function(brdEngine, cfg) { this.brdEngine = brdEngine; this.cfg = cfg || {}; diff -r 76d257640b7d -r 94e1b2d0bd31 board.js --- a/board.js Thu Sep 11 20:01:40 2014 +0300 +++ b/board.js Mon Sep 15 02:49:02 2014 +0300 @@ -1,10 +1,13 @@ +"use strict"; + +/** @fileOverview Board engines with optimised primitives. */ //////////////////////////////////////////////////////////////// -// Board as linear array. +/** Create board on linear array. + * Extract data from 'brd' if present. + * @param brd 2d array + * @constructor */ //////////////////////////////////////////////////////////////// - -/* Create board on linear array. - * Extract data from 'brd' (which is 2d array) if present. */ function BoardArr(brd) { this.brd = [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]; if (brd) { @@ -13,11 +16,11 @@ this.brd[4*i + j] = brd[i][j]; } } -/* Doesn't designed to be efficient. */ +/** Get [i][j] element. */ BoardArr.prototype.get = function(i, j) { return this.brd[4*i + j]; } -/* Doesn't designed to be efficient. */ +/** Set [i][j] element. */ BoardArr.prototype.set = function(i, j, val) { this.brd[4*i + j] = val; } @@ -40,11 +43,11 @@ //////////////////////////////////////////////////////////////// -// Board as 2d array. +/** Create board on 2d array. + * Extract data from 'brd' if present. + * @param brd 2d array + * @constructor */ //////////////////////////////////////////////////////////////// - -/* Create board on 2d array. - * Extract data from brd (which is 2d array) if present. */ function BoardArr2d(brd) { this.brd = [[0,0,0,0],[0,0,0,0],[0,0,0,0],[0,0,0,0]]; if (brd) { @@ -53,9 +56,11 @@ this.brd[i][j] = brd[i][j]; } } +/** Get [i][j] element. */ BoardArr2d.prototype.get = function(i, j) { return this.brd[i][j]; } +/** Set [i][j] element. */ BoardArr2d.prototype.set = function(i, j, val) { this.brd[i][j] = val; } @@ -724,11 +729,11 @@ //////////////////////////////////////////////////////////////// -// Board as properties. +/** Create board as properties of object. + * Extract data from 'brd' if present. + * @param brd 2d array + * @constructor */ //////////////////////////////////////////////////////////////// - -/* Create board as properties of object. - * Extract data from 'brd' (which is 2d array) if present. */ function BoardObj(brd) { if (brd) this.brd = { aa: brd[0][0], ab: brd[0][1], ac: brd[0][2], ad: brd[0][3], @@ -742,11 +747,11 @@ da: 0, db: 0, dc: 0, dd: 0 }; } BoardObj.arrMap = [["aa", "ab", "ac", "ad"], ["ba", "bb", "bc", "bd"], ["ca", "cb", "cc", "cd"], ["da", "db", "dc", "dd"]]; -/* Doesn't designed to be efficient. */ +/** Get [i][j] element. */ BoardObj.prototype.get = function(i, j) { return this.brd[BoardObj.arrMap[i][j]]; } -/* Doesn't designed to be efficient. */ +/** Set [i][j] element. */ BoardObj.prototype.set = function(i, j, val) { this.brd[BoardObj.arrMap[i][j]] = val; } diff -r 76d257640b7d -r 94e1b2d0bd31 perf.js --- a/perf.js Thu Sep 11 20:01:40 2014 +0300 +++ b/perf.js Mon Sep 15 02:49:02 2014 +0300 @@ -1,10 +1,9 @@ "use strict"; //////////////////////////////////////////////////////////////// -// Performance testing toolkit. +/** @fileOverview Performance testing toolkit. */ //////////////////////////////////////////////////////////////// - /* Invoce 'fn' function 'n' times with 'this' set to 'ctx'. * Use 'ctx' to initialise test and to pass state between calls. */ function perf(msg, fn, n, ctx) { diff -r 76d257640b7d -r 94e1b2d0bd31 rule.js --- a/rule.js Thu Sep 11 20:01:40 2014 +0300 +++ b/rule.js Mon Sep 15 02:49:02 2014 +0300 @@ -1,5 +1,8 @@ "use strict"; +/** @fileOverview Game/world rules. */ + +/** @namespace */ var board = {}; board.create = function() { var brd = []; @@ -77,6 +80,7 @@ return {score: score, max: max}; } +/** @namespace */ board.row = {}; board.row.init = function() { return {stack: [], curr: 0}; @@ -100,6 +104,8 @@ if (state.curr !== 0) state.stack.push(state.curr); } + +/** @namespace */ board.move = {}; board.move.up = board.move.upOrig = function(brd) { var updated = false;