From 1b7ed67f3edd2bef9813ef5eb4fe472f9a8a4b6e Mon Sep 17 00:00:00 2001 From: Alexander Popov Date: Thu, 8 Jul 2021 01:38:10 +0300 Subject: [PATCH] JSDoc --- .gitignore | 1 - docs/DOCS.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++ js/areas.js | 7 +++ js/buttons.js | 12 +++++ js/draw.js | 23 ++++++++ js/engine.js | 14 +++-- js/game.js | 10 ++++ js/index.js | 3 +- js/music.js | 5 ++ 9 files changed, 211 insertions(+), 6 deletions(-) create mode 100644 docs/DOCS.md diff --git a/.gitignore b/.gitignore index a450e56..504afef 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,2 @@ node_modules/ package-lock.json -docs/DOCS.md diff --git a/docs/DOCS.md b/docs/DOCS.md new file mode 100644 index 0000000..52b6a43 --- /dev/null +++ b/docs/DOCS.md @@ -0,0 +1,142 @@ + + +## setAreas + +Устанавливает размеры и положение зон для отрисовки + +### Parameters + +* `canvas` **[Object][1]** +* `landscape_orientation` **Bool** текущая ориентация игры +* `logoImage` **[Image][2]** логотип + +Returns **[Object][1]** список зон + +## getMousePos + +Возвращает + +### Parameters + +* `canvas` **[Object][1]** canvas с которого считывается позиция курсора +* `event` **[Event][3]** + +Returns **[Object][1]** координаты X, Y положения курсора на canvas + +## isInside + +Проверяет положение курсора в области объекта + +### Parameters + +* `mousePos` **[Object][1]** { x:, y: } курсора мыши +* `rect` **[Object][1]** квадратная область + +Returns **Bool** + +## clearContext + +### Parameters + +* `canvas` **[Object][1]** canvas object +* `color` **[String][4]** строка с цветом (HEX, либо имя, либо rgba, etc) + +## getCenterH + +Возвращает X координату для центрировки объекта + +### Parameters + +* `canvasWidth` **Integer** +* `objectWidth` **Integer** + +Returns **Integer** X координата + +## getCenterV + +Возвращает Y координату для центрировки объекта + +### Parameters + +* `canvasHeight` **Integer** +* `objectHeight` **Integer** + +Returns **Integer** Y координата + +## drawProgressBar + +Рисует полосу прогресса с визуализацией правильных и неправильных ответов + +### Parameters + +* `context` +* `area` **[Object][1]** зона в которой будет отрисовываться объект +* `colors` **[Object][1]** объект цветов +* `questions` **[Object][1]** объект вопросов + +## imagePreloader + +Функция, которая загружает изображения в документ +и по завершению выполнятся callback() функция + +### Parameters + +* `images` **[Array][5]** массив с именами файлов +* `callback` **[Function][6]** callback() функция + +## shuffle + +Функция случайным образом перемешивает массив + +### Parameters + +* `array` **[Array][5]** массив, элементы которого будут перемешаны + +## setOrientation + +Функция возвращает ориентацию игры в зависимости от размера canvas + +### Parameters + +* `canvas` **[Object][1]** canvas object + +Returns **Bool** значение, которое присвается landscape_orientation в index.js + +## checkAnswer + +Проверяет правильность ответа на вопрос и устанавливает статус ответа в верно/неверно + +### Parameters + +* `quest` **[Object][1]** объект вопроса с вариантами ответа и правильным вариантом +* `answer` **[String][4]** + +## restartGame + +При выполнении перемешивает вопросы и варианты ответов и запускает игру сначала + +### Parameters + +* `game` **[Object][1]** объект игрового процесса +* `quests` **[Object][1]** объект с вопросами + +## playMusic + +Воспроизводит фоновую музыку + +### Parameters + +* `config` **[Object][1]** объект с параметрами движка +* `music` **AudioContext** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/API/HTMLImageElement/Image + +[3]: https://developer.mozilla.org/docs/Web/API/Event + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function diff --git a/js/areas.js b/js/areas.js index 042f2c6..ac2f90a 100644 --- a/js/areas.js +++ b/js/areas.js @@ -2,6 +2,13 @@ import config from './config.json'; import * as Draw from './draw.js' +/** + * Устанавливает размеры и положение зон для отрисовки + * @param {Object} canvas + * @param {Bool} landscape_orientation текущая ориентация игры + * @param {Image} logoImage логотип + * @return {Object} список зон + */ export function setAreas(canvas, landscape_orientation, logoImage) { let areasArray = null; diff --git a/js/buttons.js b/js/buttons.js index 260a6fd..df43c1c 100644 --- a/js/buttons.js +++ b/js/buttons.js @@ -1,5 +1,11 @@ // функции обработки кнопок +/** + * Возвращает + * @param {Object} canvas canvas с которого считывается позиция курсора + * @param {Event} event + * @return {Object} координаты X, Y положения курсора на canvas + */ export function getMousePos(canvas, event) { let rect = canvas.getBoundingClientRect(); @@ -9,6 +15,12 @@ export function getMousePos(canvas, event) { }; } +/** + * Проверяет положение курсора в области объекта + * @param {Object} mousePos { x:, y: } курсора мыши + * @param {Object} rect квадратная область + * @return {Bool} + */ export function isInside(mousePos, rect) { return mousePos.x > rect.x && mousePos.x < rect.x + rect.w && mousePos.y < rect.y + rect.h && mousePos.y > rect.y; } diff --git a/js/draw.js b/js/draw.js index 0e0960c..43a38a6 100644 --- a/js/draw.js +++ b/js/draw.js @@ -1,5 +1,9 @@ // функции рисоввания +/** + * @param {Object} canvas canvas object + * @param {String} color строка с цветом (HEX, либо имя, либо rgba, etc) + */ export function clearContext(canvas, color) { let cW = canvas.width; let cH = canvas.height; @@ -41,10 +45,22 @@ export function placeImage(canvas, area, imageFile, colors) { } } +/** + * Возвращает X координату для центрировки объекта + * @param {Integer} canvasWidth + * @param {Integer} objectWidth + * @return {Integer} X координата + */ export function getCenterH(canvasWidth, objectWidth) { return canvasWidth / 2 - objectWidth / 2; } +/** + * Возвращает Y координату для центрировки объекта + * @param {Integer} canvasHeight + * @param {Integer} objectHeight + * @return {Integer} Y координата + */ export function getCenterV(canvasHeight, objectHeight) { return canvasHeight / 2 - objectHeight / 2; } @@ -74,6 +90,13 @@ export function drawInfo(canvas, landscape_orientation) { // } } +/** + * Рисует полосу прогресса с визуализацией правильных и неправильных ответов + * @param {} context + * @param {Object} area зона в которой будет отрисовываться объект + * @param {Object} colors объект цветов + * @param {Object} questions объект вопросов + */ export function drawProgressBar(context, area, colors, questions) { let sizeProgressItem = area.w / questions.length; diff --git a/js/engine.js b/js/engine.js index 07572f1..583b212 100644 --- a/js/engine.js +++ b/js/engine.js @@ -1,5 +1,11 @@ import config from './config.json'; +/** + * Функция, которая загружает изображения в документ + * и по завершению выполнятся callback() функция + * @param {Array} images массив с именами файлов + * @param {Function} callback callback() функция + */ export function imagePreloader(images, callback) { let counter = 0; @@ -15,9 +21,11 @@ export function imagePreloader(images, callback) { } } +/** + * Функция случайным образом перемешивает массив + * @param {Array} array массив, элементы которого будут перемешаны + */ export function shuffle(array) { - // ф - for (let i = array.length - 1; i > 0; i--) { const j = Math.floor(Math.random() * (i + 1)); [array[i], array[j]] = [array[j], array[i]]; @@ -28,7 +36,7 @@ export function shuffle(array) { /** * Функция возвращает ориентацию игры в зависимости от размера canvas * @param {Object} canvas canvas object - * @return {Bool} landscape_orientation + * @return {Bool} значение, которое присвается landscape_orientation в index.js */ export function setOrientation(canvas) { let landscape_orientation = null; diff --git a/js/game.js b/js/game.js index c399ec4..7ee9df1 100644 --- a/js/game.js +++ b/js/game.js @@ -2,6 +2,11 @@ import { shuffle } from './engine.js'; +/** + * Проверяет правильность ответа на вопрос и устанавливает статус ответа в верно/неверно + * @param {Object} quest объект вопроса с вариантами ответа и правильным вариантом + * @param {String} answer + */ export function checkAnswer(quest, answer) { if (Array.isArray(quest.rightAnswer)) { let lowerCaseArray = []; @@ -24,6 +29,11 @@ export function checkAnswer(quest, answer) { } } +/** + * При выполнении перемешивает вопросы и варианты ответов и запускает игру сначала + * @param {Object} game объект игрового процесса + * @param {Object} quests объект с вопросами + */ export function restartGame(game, quests) { // shuffle quests and answers order shuffle(quests); diff --git a/js/index.js b/js/index.js index f7a5c9a..39aca4b 100644 --- a/js/index.js +++ b/js/index.js @@ -44,8 +44,7 @@ window.onload = function() { images.logo = imageLogo; let loadingImages = []; - loadingImages.push(gameData.result.notPassed); - loadingImages.push(gameData.result.passed); + loadingImages.push(gameData.result.notPassed, gameData.result.passed); for (const [key, value] of Object.entries(gameData.questions)) { loadingImages.push(value.image); diff --git a/js/music.js b/js/music.js index c54716f..4aea572 100644 --- a/js/music.js +++ b/js/music.js @@ -1,3 +1,8 @@ +/** + * Воспроизводит фоновую музыку + * @param {Object} config объект с параметрами движка + * @param {AudioContext} music + */ export function playMusic(config, music) { let request = new XMLHttpRequest();