doc code

src/FlagsQuiz/FlagQuiz.tsx

@@ -62,7 +62,7 @@ function FlagQuiz(): JSX.Element {
   const WRONG_COLOR = 4;
   const SELECTED_COLOR = 0;
 
-
+  // load puzzle from url
   useEffect(() => {
     if (window.location.pathname) {
       const puzzleUrl = cleanUrlParams(window.location.search.substring(10));
@@ -74,13 +74,20 @@ function FlagQuiz(): JSX.Element {
     }
   }, []);
 
-
+  // get custom wikis
   const getCustomWikis = (puzzleId: number) => {
     PuzzleService.getCustomWikis(puzzleId).then((customWiki: CustomWiki[]) => {
       setPuzzleCustomWiki(customWiki);
     });
   };
 
+
+  /**
+   * Handles the click event on the map.
+   * @param info The PieceEvent object containing the information about the clicked piece.
+   * @returns Nothing.
+   * @remarks If the clicked piece is found and the puzzle has wiki enabled, the wiki info will be shown.
+  */
   const onClickMapHandler = (info: PieceEvent) => {
     if (!winner) return;
     if (info.object) {
@@ -135,6 +142,7 @@ function FlagQuiz(): JSX.Element {
     GameTime.seconds = 0;
   };
 
+  /* show wiki info */
   const onShowWikiInfoHandler = (val: boolean) => {
     if (
       val &&
@@ -346,6 +354,9 @@ function FlagQuiz(): JSX.Element {
     return pieceSelectedAux;
   };
 
+  /**
+   * Sets the color of a puzzle piece to CORRECT_COLOR and selects the next piece for the quiz.
+   */
   const onCorrectAnswerHandler = () => {
     const correctsAux = [
       ...corrects,
@@ -363,6 +374,9 @@ function FlagQuiz(): JSX.Element {
     nextPiece();
   };
 
+  /**
+   * Sets the color of a puzzle piece to WRONG_COLOR and selects the next piece for the quiz.
+   */
   const onWrongAnswerHandler = () => {
     const failsAux = [...fails, pieces[pieceSelected].properties.cartodb_id];
     setFails(failsAux);
@@ -412,7 +426,7 @@ function FlagQuiz(): JSX.Element {
         ConfigService.cookieDays
       );
     }
-
+    // get random piece not found
     const randomPiece = getRandomPieceNotFounds(pieces);
     const pieceSelectedAux = pieces[randomPiece];
     setPieceSelectedData(pieceSelectedAux);
@@ -421,14 +435,16 @@ function FlagQuiz(): JSX.Element {
     setFounds([...founds, pieces[randomPiece].properties.cartodb_id]);
 
     generateQuestions(pieceSelectedAux);
-
+
+    //calculate centroid
     const centroid = turf.centroid(pieceSelectedAux.geometry);
+    //calculate zoom
     let zoom =
       calculateZoom(turf.bbox(pieceSelectedAux.geometry)) * ZOOM_OUT_FACTOR;
     if (zoom < MIN_ZOOM) {
       zoom = MIN_ZOOM;
     }
-
+    // animate to piece position and zoom
     const newViewState: ViewState = {
       ...viewState,
       longitude: centroid.geometry.coordinates[0],

src/FlagsQuiz/Quiz/Flag.tsx

@@ -14,6 +14,7 @@ function Flag({ flagImageUrl }: { flagImageUrl: string }): JSX.Element {
   const flagRef = useRef<THREE.Mesh>(null);
   const flagFakeShadow = useRef<THREE.Mesh>(null);
 
+  // Load flag texture and apply it to the flag mesh
   useEffect(() => {
     if (flagRef.current) {
       const loader = new THREE.TextureLoader();
@@ -60,6 +61,7 @@ function Flag({ flagImageUrl }: { flagImageUrl: string }): JSX.Element {
     }
   }, []);
 
+  // Animate flag vertices
   useFrame(() => {
     const time = Date.now() * SPEED; // Cambia el factor para ajustar la velocidad del movimiento
 

src/FlagsQuiz/Quiz/FlagSelector.tsx

@@ -14,7 +14,7 @@ function FlagSelector({ flagImageUrl }: { flagImageUrl: string }): JSX.Element {
   const initialFlagPositionOutsideLeft: Vector3 = [-20, -0.3, 0.4];
   const flagPosition: Vector3 = [0, -0.3, 0.4];
 
-  // Creamos un hook useTransition para animar la entrada y salida de la bandera antigua
+  // create a useTransition hook to animate the entry and exit of the old flag
   const transitions = useTransition(flagImageUrl, {
     from: { position: initialFlagPositionOutsideRight },
     enter: { position: flagPosition },
@@ -27,7 +27,7 @@ function FlagSelector({ flagImageUrl }: { flagImageUrl: string }): JSX.Element {
     <React.Fragment>
 
       {transitions((style, item) => {
-        // Usamos el componente animated para renderizar la bandera antigua con la transición animada
+        // Use the animated component to render the old flag with the animated transition
         return (
           item && (
             <animated.group position={style.position}>

src/FlagsQuiz/Quiz/PieceQuiz.tsx

@@ -49,6 +49,7 @@ function PieceQuiz({
   const [backgroundImage, setBackgroundImage] = useState("");
   const [quizResponse, setQuizResponse] = useState(false)
 
+  // get background image from distance from ecuador
   useEffect(() => {
     if (pieceSelectedData?.geometry === undefined) return;
     const centroid = turf.centroid(pieceSelectedData.geometry);
@@ -58,11 +59,9 @@ function PieceQuiz({
       centroid.geometry.coordinates[1]
     );
 
-    // get n from 1 to flagQuizBackgrounds number proportionally to distance
+    // get distance from ecuador and multiply by flagQuizBackgrounds number
     const n = Math.floor(distance * ConfigService.flagQuizBackgrounds) + 1;
 
-    // console.log(`distance: ${distance} n: ${n}`);
-
     setBackgroundImage(`./flagQuiz/flagBackground${n}.jpeg`);
   }, [pieceSelectedData]);
 
@@ -78,6 +77,7 @@ function PieceQuiz({
       });
   }, [lang]);
 
+  // set variant for buttons if quizResponse is true
   const variant = (c: PieceProps) => {
     if (quizResponse) {
       if (c.properties.cartodb_id === pieceSelectedData.properties.cartodb_id) {
@@ -106,7 +106,8 @@ function PieceQuiz({
   });
 
 
-
+  // on click button check if correct or wrong
+  // and init animate button and show correct or wrong
   const onClickHandler = (c: PieceProps) => {
   //prevent clicks if quizResponse is true
   if (quizResponse) return;
@@ -122,13 +123,14 @@ function PieceQuiz({
       }, ConfigService.flagQuizResponseTime);
 
   }
-
+  // get flag image url
   const getFlag = (puzzleId: number, c: PieceProps): string => {
     return `../customFlags/${puzzleId.toString()}/1024/${
       c.properties.cartodb_id
     }.png`;
   };
-
+
+  // show timer if not winner
   const showTimer =
     winner || loading ? null : (
       <Timer puzzleSelected={puzzleSelected} name="quizSeconds" />

src/MapPuzzle.tsx

@@ -55,6 +55,10 @@ function MapPuzzle(): JSX.Element {
   const [viewState, setViewState] = useState({} as ViewState);
   const [lang, setLang] = useState("");
   const { i18n } = useTranslation();
+
+  /*
+  * Load the game on start
+  */
   useEffect(() => {
     if (window.location.pathname) {
       const puzzleUrl = cleanUrlParams(window.location.search.substring(5));
@@ -69,7 +73,10 @@ function MapPuzzle(): JSX.Element {
   useEffect(() => {
     handleResize();
   }, [height]);
-
+
+  /*
+  * Handle resize of the window set the height of tools panel
+  */
   const handleResize = () => {
     let heightAux = window.innerHeight;
     if (window.innerWidth < 992) {
@@ -83,7 +90,12 @@ function MapPuzzle(): JSX.Element {
   };
 
 
-  /* load game from db */
+  /* 
+  * load game from db 
+  * @param puzzleId 
+  * @returns void
+  * @remarks Load the game from db and set the pieces and founds
+  */
   const loadGame = (puzzleId: number) => {
     const langAux = getLang();
     i18n.changeLanguage(langAux);
@@ -131,6 +143,11 @@ function MapPuzzle(): JSX.Element {
     });
   };
 
+  /*
+  * Restore cookies from game
+  * @param puzzleId
+  * @returns void
+  */
   const restoreCookies = (puzzleId: number) => {
     const cookieFounds = getCookie("founds" + puzzleId);
     if (cookieFounds) {
@@ -152,6 +169,14 @@ function MapPuzzle(): JSX.Element {
     }
   };
 
+  /*
+  * Load pieces by lang
+  * @param puzzleSelectedAux
+  * @param piecesAux
+  * @param langAux
+  * @returns void
+  * @remarks Load the pieces from db and set the pieces and founds
+  * */
   function loadPiecesByLang(
     puzzleSelectedAux: number,
     piecesAux: PieceProps[],
@@ -199,6 +224,7 @@ function MapPuzzle(): JSX.Element {
     setLang(lang);
   };
 
+  /* get custom centroids from db */
   const getCustomCentroids = (puzzleId: number) => {
     PuzzleService.getCustomCentroids(puzzleId).then(
       (customCentroids: CustomCentroids[]) => {
@@ -207,12 +233,14 @@ function MapPuzzle(): JSX.Element {
     );
   };
 
+  /* get custom wikis from db */
   const getCustomWikis = (puzzleId: number) => {
     PuzzleService.getCustomWikis(puzzleId).then((customWiki: CustomWiki[]) => {
       setPuzzleCustomWiki(customWiki);
     });
   };
 
+  /* check if the game is finished */
   useEffect(() => {
     if (pieces.length - founds.length <= 0 && pieces.length > 0) {
       setWinner(true);