From 4379b7ea77de4f8ec96b4d585f8fe5bad032fe31 Mon Sep 17 00:00:00 2001
From: HugoFara <contact@hugofara.net>
Date: Mon, 1 Apr 2024 19:01:27 +0200
Subject: [PATCH] Code doc with psalm, and manual changes. psalm configuration
 was also updated to remove warnings.

---
 do_test_test.php           |  2 +-
 do_text_text.php           |  5 +++--
 edit_archivedtexts.php     |  2 +-
 edit_languages.php         |  3 ++-
 edit_tags.php              |  2 +-
 edit_texttags.php          |  2 +-
 edit_word.php              |  5 +----
 ggl.php                    | 13 ++++++-------
 glosbe_api.php             |  2 +-
 inc/database_connect.php   |  6 ++----
 inc/session_utility.php    | 24 +++++++++++++-----------
 inline_edit.php            |  2 +-
 install_demo.php           |  2 +-
 new_word.php               |  2 +-
 print_text.php             |  2 +-
 psalm.xml                  |  2 ++
 set_word_on_hover.php      |  2 +-
 settings.php               |  2 +-
 show_word.php              |  2 +-
 src/js/audio_controller.js |  2 +-
 statistics.php             |  2 +-
 table_set_management.php   |  2 +-
 22 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/do_test_test.php b/do_test_test.php
index 97b7c4b16..bbf1827b9 100644
--- a/do_test_test.php
+++ b/do_test_test.php
@@ -81,7 +81,7 @@ function do_test_get_identifier($selection, $sess_testsql, $lang, $text): array
  *
  * @return string SQL projection (selection) string
  */
-function do_test_get_test_sql($selection, $sess_testsql, $lang, $text)
+function do_test_get_test_sql($selection, $sess_testsql, $lang, $text): string
 {
     $identifier = do_test_get_identifier($selection, $sess_testsql, $lang, $text);
     $testsql = do_test_test_get_projection($identifier[0], $identifier[1]);
diff --git a/do_text_text.php b/do_text_text.php
index cb145b4a8..bb2d9a814 100644
--- a/do_text_text.php
+++ b/do_text_text.php
@@ -851,8 +851,9 @@ function do_text_text_content($textid, $only_body = true): void
 }
 
 /*
- * Uncoment to use as a page, deprecated behavior in LWT-fork, will be removed in 3.0.0
-if (isset($_REQUEST['text'])) {
+Uncoment to use as a page, deprecated behavior in LWT-fork, will be removed in 3.0.0
+
+ if (isset($_REQUEST['text'])) {
     do_text_text_content($_REQUEST['text'], false);
 }
 */
diff --git a/edit_archivedtexts.php b/edit_archivedtexts.php
index 88f776c6b..8ba4b2e5f 100644
--- a/edit_archivedtexts.php
+++ b/edit_archivedtexts.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Manage archived texts
  * 
  * Call: edit_archivedtexts.php?....
diff --git a/edit_languages.php b/edit_languages.php
index 9cc8ad64c..fdccc78ee 100644
--- a/edit_languages.php
+++ b/edit_languages.php
@@ -369,7 +369,8 @@ function load_language($lgid)
     return $language;
 }
 
-function edit_languages_displayThirdPartyVoiceAPI() {
+function edit_languages_displayThirdPartyVoiceAPI(): void
+{
     ?>
 <h2>Third-Party Voice API</h2>
 <p>
diff --git a/edit_tags.php b/edit_tags.php
index ce0b59ffc..c9f9fbba3 100644
--- a/edit_tags.php
+++ b/edit_tags.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Manage tags
  * 
  * Call: edit_tags.php?....
diff --git a/edit_texttags.php b/edit_texttags.php
index c13d5602b..fc3ea5c6a 100644
--- a/edit_texttags.php
+++ b/edit_texttags.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Manage tags
  * 
  * Call: edit_texttags.php?....
diff --git a/edit_word.php b/edit_word.php
index 8b16a94b9..7d4f264a0 100644
--- a/edit_word.php
+++ b/edit_word.php
@@ -179,10 +179,7 @@ function change_term_display($wid, $translation, $hex): void
 }
 
 // INS/UPD
-/*
- * @return void
- */
-function edit_word_do_operation($translation, $fromAnn)
+function edit_word_do_operation($translation, $fromAnn): void
 {
     $hex = null;
     $textlc = trim(prepare_textdata($_REQUEST["WoTextLC"]));
diff --git a/ggl.php b/ggl.php
index ac0088a2f..7dc9b4efe 100644
--- a/ggl.php
+++ b/ggl.php
@@ -1,8 +1,7 @@
 <?php
 
-/*
- * \file
- * \brief Google Translate interface
+/**
+ * Google Translate interface
  * 
  * Call: ggl.php?text=[text]&sl=[source language]&tl=[target language] ... translate text
  *     ... sent=[int] ... single sentence mode.
@@ -26,7 +25,7 @@
 
 use function Lwt\Includes\getGoogleTimeToken;
 
-/*
+/**
  * Translate a single sentence using Google Translate.
  * 
  * @param string $text        Text to translate
@@ -46,7 +45,7 @@ function translate_sentence($text, $translation): void
     <?php
 }
 
-/*
+/**
  * Translate input text using Google Translate.
  * 
  * @param string $text   Text to translate
@@ -110,7 +109,7 @@ function translate_term($text, $file, $sl, $tl): void
     <?php
 }
 
-/*
+/**
  * Translate input text using Google Translate.
  * 
  * @param string $text Text to translate
@@ -147,7 +146,7 @@ function translate_text($text, $sl, $tl, $sentence_mode): void
     echo $gglink;
 }
 
-/*
+/**
  * Translate input text using Google Translate.
  * 
  * @param string $text Text to translate
diff --git a/glosbe_api.php b/glosbe_api.php
index 1c01060fc..49b3d878b 100644
--- a/glosbe_api.php
+++ b/glosbe_api.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Call Glosbe Translation API, analyze and present JSON results
  * for easily filling the "new word form"
  * 
diff --git a/inc/database_connect.php b/inc/database_connect.php
index 5c4891824..0e261a750 100644
--- a/inc/database_connect.php
+++ b/inc/database_connect.php
@@ -1397,8 +1397,6 @@ function (k,v) {
  *
  * @param int[] $wl All the different expression length in the language.
  *
- * @return string SQL-formatted query string
- *
  * @global string $tbpref Database table prefix
  */
 function checkExpressions($wl): void
@@ -1818,7 +1816,7 @@ function update_database($dbname)
 }
 
 
-/*
+/**
  * Add a prefix to table in a SQL query string.
  * 
  * @param string $sql_line SQL string to prefix.
@@ -2160,7 +2158,7 @@ function get_database_prefixes(&$tbpref)
 }
 
 /**
- * @var mysqli $DBCONNECTION Connection to the database
+ * @var \mysqli $DBCONNECTION Connection to the database
  */
 $DBCONNECTION = connect_to_database(
     $server, $userid, $passwd, $dbname, $socket ?? ""
diff --git a/inc/session_utility.php b/inc/session_utility.php
index 050bbe95f..5d040ed9c 100644
--- a/inc/session_utility.php
+++ b/inc/session_utility.php
@@ -726,19 +726,19 @@ function get_selected($value, $selval): string
 
 /**
  * Create a projection operator do perform word test.
- * 
+ *
  * @param string    $key   Type of test. 
  *                         - 'words': selection from words
  *                         - 'texts': selection from texts
  *                         - 'lang': selection from language
  *                         - 'text': selection from single text
  * @param array|int $value Object to select.
- * 
+ *
  * @return string SQL projection necessary
- * 
+ *
  * @global string $tbpref
  */
-function do_test_test_get_projection($key, $value)
+function do_test_test_get_projection($key, $value): string
 {
     global $tbpref;
     $testsql = null;
@@ -2202,7 +2202,7 @@ function textwordcount($textID): void
  *
  * @param int $textid Text ID
  *
- * @return string HTML result
+ * @return int Number of words
  *
  * @global string $tbpref
  */
@@ -2769,11 +2769,11 @@ function getScriptDirectionTag($lid): string
  * @param string|int $lid  Language ID
  * @param int        $len  Number of words in the expression
  *
- * @return (string|int)[] Each found multi-word details
+ * @return (int|string)[][] Each found multi-word details
  *
  * @global string $tbpref Table name prefix
  *
- * @psalm-return list{array<int, string>, list{0?: string,...}}
+ * @psalm-return list{0?: array{SeID: int, TxID: int, position: int, term: string},...}
  */
 function findMecabExpression($text, $lid): array
 {
@@ -2935,9 +2935,11 @@ function insertExpressionFromMeCab($textlc, $lid, $wid, $len, $mode): array
  * @param string     $textlc Text to insert in lower case
  * @param string|int $lid    Language ID
  *
- * @return (string|int)[] Each inserted mutli-word details
+ * @return (int|null|string)[][] Each inserted mutli-word details
  *
  * @global string $tbpref Table name prefix
+ *
+ * @psalm-return list{0?: array{SeID: int, SeTxID: int, position: int, term: null|string, term_display: null|string},...}
  */
 function findStandardExpression($textlc, $lid): array
 {
@@ -3587,12 +3589,12 @@ function create_save_ann($textid): string
 
 /**
  * Truncate the database, remove all data belonging by the current user.
- * 
+ *
  * Keep settings.
- * 
+ *
  * @global $tbpref
  */
-function truncateUserDatabase()
+function truncateUserDatabase(): void
 {
     global $tbpref;
     runsql("TRUNCATE {$tbpref}archivedtexts", '');
diff --git a/inline_edit.php b/inline_edit.php
index c0bc9077e..5baf49f59 100644
--- a/inline_edit.php
+++ b/inline_edit.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Call: inline_edit.php?...
  *  ...
  * 
diff --git a/install_demo.php b/install_demo.php
index 5d8e89ca9..fd1d81583 100644
--- a/install_demo.php
+++ b/install_demo.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Install LWT Demo Database
  * 
  * Call: install_demo.php
diff --git a/new_word.php b/new_word.php
index c9d815e99..1576450ba 100644
--- a/new_word.php
+++ b/new_word.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * New word, created while reading or testing
  * 
  * Call: new_word.php?...
diff --git a/print_text.php b/print_text.php
index d8ec5f04f..822b88826 100644
--- a/print_text.php
+++ b/print_text.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Print a text
  * 
  * Call: print_text.php?text=[textid]&...
diff --git a/psalm.xml b/psalm.xml
index 80aaccded..fdf39b004 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -2,6 +2,8 @@
 <psalm
     errorLevel="4"
     resolveFromConfigFile="true"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
diff --git a/set_word_on_hover.php b/set_word_on_hover.php
index 0b76cdfc9..fde2f5694 100644
--- a/set_word_on_hover.php
+++ b/set_word_on_hover.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * PHP version 8.1
  * 
  * @category Helper_Frame
diff --git a/settings.php b/settings.php
index adbbfbaaa..d8a144436 100644
--- a/settings.php
+++ b/settings.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Preferences / Settings 
  * 
  * Call: settings.php?....
diff --git a/show_word.php b/show_word.php
index 5e5c47c06..6778da766 100644
--- a/show_word.php
+++ b/show_word.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Show term
  * 
  * Call: show_word.php?wid=...&ann=...
diff --git a/src/js/audio_controller.js b/src/js/audio_controller.js
index db3edaa6d..3b2bb28a5 100644
--- a/src/js/audio_controller.js
+++ b/src/js/audio_controller.js
@@ -4,7 +4,7 @@
  * @license Unlicense
  */
 
-/*
+/**
  * An audio controller.
  */
 const lwt_audio_controller = {
diff --git a/statistics.php b/statistics.php
index d746effe9..3f8166d19 100644
--- a/statistics.php
+++ b/statistics.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Display statistics
  * 
  * Call: statistics.php
diff --git a/table_set_management.php b/table_set_management.php
index e4c827a97..fda29c59b 100644
--- a/table_set_management.php
+++ b/table_set_management.php
@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * Analyse DB tables, and manage Table Sets
  * 
  * Call: table_set_management.php