Merge pull request #111 from ThomasRubini/jsDoc

truthinquiry/static/js/game.js

@@ -73,6 +73,11 @@ function showEmotionAndCulpritChoicesView() {
     showFirstClassElement("emotion_and_culprit_choices");
 }
 
+/**
+ * Parse the gamedata object to retreive the room in which the npc passed as parameter is
+ * located and the second npc located in the same room. When the passed npc is alone in the
+ * room, a npc is choosen at random as the returned partener
+ */
 function getNpcLocationAndPartner(npcid) {
     const data = {};
     const npcidInt = parseInt(npcid);
@@ -96,6 +101,11 @@ function getNpcLocationAndPartner(npcid) {
     return data;
 }
 
+/**
+ * Parse the gamedata object to retreive the room in which the npc passed as parameter is
+ * located and the second npc located in the same room. When the passed npc is alone in the
+ * room, a npc is choosen at random as the returned partener
+ */
 function disableCulpritButtons(culprit_choices_element, selected_suspect) {
     let childrenCulpritChoicesElement = culprit_choices_element.children;
 
@@ -112,12 +122,16 @@ function disableCulpritButtons(culprit_choices_element, selected_suspect) {
     }
 }
 
+/**
+ * Return the npc designed as the "culprit" of the crime, the culprit
+ * is determined by being the only npc alone in a room.
+ */
 function getCulprit() {
     let culprit = null;
 
-    Object.values(gameData["rooms"]).forEach(element => {
-        if (element['npcs'].length === 1) {
-            culprit = element['npcs'][0];
+    Object.values(gameData["rooms"]).forEach(room => {
+        if (room['npcs'].length === 1) {
+            culprit = room['npcs'][0];
             return;  
         } 
     });
@@ -125,16 +139,31 @@ function getCulprit() {
     return culprit;
 }
 
-async function askTypeOneQuestion() {
-    askQuestion(npcLocationAndPartner => gameData["npcs"][currentNpc]["QA_1"].replace(
-        "{NPC}", gameData["npcs"][npcLocationAndPartner["partner"]]["name"]));
-}
-
+/**
+ * handler for the function call "askQuestion" for a type_zero question
+ * also known as "Where were you ?"
+ */
 async function askTypeZeroQuestion() {
     askQuestion(npcLocationAndPartner => gameData["npcs"][currentNpc]["QA_0"].replace(
         "{SALLE}", npcLocationAndPartner["room"]));
 }
 
+/**
+ * handler for the function call "askQuestion" for a type_one question
+ * also known as "With who were you with ?"
+ */
+async function askTypeOneQuestion() {
+    askQuestion(npcLocationAndPartner => gameData["npcs"][currentNpc]["QA_1"].replace(
+        "{NPC}", gameData["npcs"][npcLocationAndPartner["partner"]]["name"]));
+}
+
+/**
+ * This function primary goal is to display the answer to the question the player
+ * asked to a npc. 
+ * It parses the gamedata object to retreive the answer of the npc
+ * and fill the variables left in the string accordingly to the type of the question.
+ * Then it fetches the reacion of the npc and diplays it all.
+ */
 async function askQuestion(buildAnswer) {
     unsetQuestionButtonsListeners();
 
@@ -157,6 +186,9 @@ async function askQuestion(buildAnswer) {
     setQuestionButtonsListeners();
 }
 
+/**
+ * This function sends the player's answers to the server
+ */
 async function sendAnswers() {
     const selections = document.getElementsByClassName("suspect_emotion_chooser");
 
@@ -172,6 +204,10 @@ async function sendAnswers() {
     return await makeAPIRequest("submitAnswers", data);
 }
 
+/**
+ * Show the screen in which the player fill the emotion of each npc
+ * then decide on which npc is the culprit.
+ */
 function renderAnswerSelectionPanel() {
     npcsIds.forEach(element => {
         const suspect = document.createElement("div");
@@ -211,6 +247,9 @@ function renderAnswerSelectionPanel() {
     });
 }
 
+/**
+ * Show the screen in which the player asks auestions to the npcs
+ */
 function renderInterrogation() {
     document.getElementById("QA_0").textContent = gameData["questions"]["QA_0"];
     document.getElementById("QA_1").textContent = gameData["questions"]["QA_1"];
@@ -242,6 +281,13 @@ function renderInterrogation() {
     });
 }
 
+
+/**
+ * Initialize the websocket for this page, its primary use is to
+ * show the final page once it receive the event that all player have finished
+ * it parses the payload send by the server containing the other players
+ * nicknames and scores.
+ */
 function initSock() {
     const socket = io({
         auth : {
@@ -320,6 +366,11 @@ function initSock() {
             });
     });
 }
+/** 
+ * This function retreive the initial gamedata of the game
+ * containing all of the needed textual ressources to make
+ * the game playable
+*/
 
 async function setGameData() {
     const response = await makeAPIRequest("getGameData");

truthinquiry/static/js/game_lobby.js

@@ -60,7 +60,7 @@ function displayWaitingForHostMessage() {
  * shown, by removing the hidden CSS class on the element.
  * </p>
  *
- * @param {boolean} errorMessage the error message to show
+ * @param {string} errorMessage the error message to show
  */
 function displayInvalidNickNameErrorMessage(errorMessage) {
     let gameStartFailedElement = document.querySelector(".game_start_failed");
@@ -105,6 +105,12 @@ function getMembers(){
 }
 // Join room functions
 
+/**
+ * This function read the username join an already existing game, 
+ * to do so it calls the joinGame endpoint with the aftermentioned 
+ * username as parameter. If the request succeeds the lobby view
+ * is displayed. 
+ */
 function joinRoom() {
     if (isNickNameInvalid()) {
         displayInvalidNickNameErrorMessage("Le nom saisi n'est pas valide.");
@@ -223,13 +229,21 @@ function unsetListenerToCopyCodeButton() {
     document.getElementById("invite_friends_button").removeEventListener("click", copyCode);
 }
 
-// Utility functions
-
+/**
+ * This predicate asks the server is the current player is the owner of the 
+ * room stored in the session cookie.
+ * @returns {boolean} true if the player is the owner of the game, false otherwise
+ */
 async function isRoomOwner() {
     const response = await makeAPIRequest("isOwner");
     return response["owner"];
 }
 
+/**
+ * This predicate asks the server is the current player has joined the 
+ * room stored in the session cookie.
+ * @returns {boolean} true if the player has joined the game, false otherwise
+ */
 async function hasJoinedRoom() {
     const response = await makeAPIRequest("hasJoined");
     return response["joined"];
@@ -317,6 +331,12 @@ function getRoomCode() {
     return document.getElementById("game_id").value;
 }
 
+/**
+ * Initialize the websocket for this page, its primary use is to
+ * show in realtime players joining the room and to start the game
+ * of every player in the same time when the game owner starts the 
+ * gane
+ */
 function initSock() {
     const socket = io({
         auth: {

truthinquiry/static/js/game_start_page.js

@@ -108,6 +108,10 @@ function areInputsValid(checkRoomCode) {
     return true;
 }
 
+
+/**
+ * Handler for the multiplayer room creation button 
+ */
 function createMultiPlayerRoom() {
     if (!areInputsValid(false)) {
         return;
@@ -118,6 +122,9 @@ function createMultiPlayerRoom() {
     startGame();
 }
 
+/**
+ * Handler for the join room button 
+ */
 function joinMultiPlayerRoom() {
     if (!areInputsValid(true)) {
         return;
@@ -197,6 +204,10 @@ function changeTheme() {
     }
 }
 
+/**
+ * This function launches a single player game. It sends the api request to
+ * create a game then it immediately start the game by sendind the startGame api
+ */
 async function startSoloGame(){
 
     if (!areInputsValid(false)) {
@@ -215,6 +226,10 @@ async function startSoloGame(){
     })
 }
 
+/**
+ * This function creates a multiplayer game by sending the createGame api call
+ * then, if no error occured, redirects to the lobby page.
+ */
 async function startGame(){
     username = document.getElementById("game_username").value;
     let data = {}
@@ -231,6 +246,12 @@ async function startGame(){
       });
 
 }
+
+/**
+ * This function read the username and the room code in order to
+ * join an already existing game, to do so it calls the joinGame endpoint
+ * with the aftermentioned username and room code as parameter. 
+ */
 async function joinGame(){
     username = document.getElementById("game_username").value;
     gameid = document.getElementById("game_room_code").value;