From c7ec1994eb13ea4c9256391f3850da5c7b2b2316 Mon Sep 17 00:00:00 2001
From: Nonimart <martinon.toinou@protonmail.com>
Date: Wed, 17 Sep 2025 14:16:16 +0200
Subject: [PATCH] REFACTOR Optimizing commentaries on utilities

---
 includes/utilities.php | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/includes/utilities.php b/includes/utilities.php
index 56717ca..df85990 100644
--- a/includes/utilities.php
+++ b/includes/utilities.php
@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Récupère tous les auteurs uniques d'une revue
+ * 
+ * Cette fonction collecte tous les auteurs des articles liés à une revue spécifique.
+ * Elle parcourt tous les articles publiés qui ont une relation avec la revue
+ * et retourne un tableau d'IDs d'auteurs uniques.
+ * 
+ * @param int $revueID L'ID de la revue pour laquelle récupérer les auteurs
+ * @return array Tableau d'IDs d'auteurs uniques
+ */
 function getRevueAuthors($revueID)
 {
 	$revueRelatedArticles = new WP_Query(array(
@@ -28,6 +38,17 @@ function getRevueAuthors($revueID)
 	return array_unique($authors);
 }
 
+/**
+ * Récupère tous les termes uniques d'une taxonomie pour une revue
+ * 
+ * Cette fonction collecte tous les termes d'une taxonomie spécifique
+ * associés aux articles d'une revue. Elle parcourt tous les articles
+ * liés à la revue et retourne les termes uniques de la taxonomie donnée.
+ * 
+ * @param int $revueID L'ID de la revue
+ * @param string $taxonomy Le nom de la taxonomie (ex: 'etiquettes', 'category')
+ * @return array Tableau d'objets de termes uniques
+ */
 function get_revue_terms($revueID, $taxonomy)
 {
 	$revueRelatedArticles = new WP_Query(array(
@@ -80,6 +101,17 @@ function count_user_articles($userID, $postType)
 }
 
 
+/**
+ * Génère un sommaire automatique à partir du contenu d'un post
+ * 
+ * Cette fonction analyse les blocs Gutenberg d'un post pour extraire
+ * tous les titres de niveau 2 (h2) et créer un index de navigation.
+ * Elle génère des ancres automatiques pour chaque titre.
+ * 
+ * @param int $postID L'ID du post à analyser
+ * @return array Tableau associatif contenant les éléments du sommaire
+ *               Chaque élément contient: title, anchor, level
+ */
 function build_sommaire_from_content($postID)
 {
 	$blocks = parse_blocks(get_the_content($postID));
@@ -137,6 +169,16 @@ function build_sommaire_from_content($postID)
 }
 
 
+/**
+ * Construit un index des notes de bas de page à partir du contenu HTML
+ * 
+ * Cette fonction analyse le contenu HTML pour détecter les liens de notes
+ * de bas de page (avec classe 'footnote-reference') et extrait leur contenu
+ * pour créer un index numéroté des notes.
+ * 
+ * @param string $content Le contenu HTML à analyser
+ * @return array Tableau des notes de bas de page avec clé, ancre et contenu
+ */
 function build_footnotes_index_from_content($content)
 {
 	if (empty($content)) {