Resolve "Complete PHP Doc"

supportedversions_fonctions.php

@@ -2,6 +2,14 @@
 
 // SPIP Standard API
 
+/**
+ * Pipeline insert_head_css.
+ *
+ * @see https://programmer.spip.net/insert_head_css,561
+ *
+ * @param string $flux
+ * @return string
+ */
 function supportedversions_insert_head_css($flux) {
 	$flux .= '<link rel="stylesheet" type="text/css" media="all" href="'.
 	find_in_path('css/supported-versions.css').
@@ -11,6 +19,8 @@ function supportedversions_insert_head_css($flux) {
 }
 
 /**
+ * Pipeline header_prive_cs.
+ *
  * @codeCoverageIgnore
  *
  * @param string $flux
@@ -20,6 +30,18 @@ function supportedversions_header_prive_css($flux) {
 	return supportedversions_insert_head_css($flux);
 }
 
+/**
+ * Balise #SUPPORTED_VERSIONS.
+ *
+ * Récupère les éléments définis dans la super globale $supportedversions
+ * Valeurs par défaut founies dans le fichier supportedversions_options.php
+ *
+ * @see https://www.spip.net/fr_article4014.html
+ * @api
+ *
+ * @param Champ $p
+ * @return Champ
+ */
 function balise_SUPPORTED_VERSIONS_dist($p) {
 	return balise_ENV_dist($p, '$GLOBALS["supportedversions"]');
 }
@@ -38,6 +60,8 @@ class SupportedVersions
 	protected static $releasesFile;
 
 	/**
+	 * @internal Définit et stocke les paramètres de configuration du calendrier, les données des releases et la date courante.
+	 *
 	 * @codeCoverageIgnore
 	 *
 	 * @return void
@@ -50,6 +74,11 @@ class SupportedVersions
 		self::compute();
 	}
 
+	/**
+	 * @internal Calcule certaines données après initialisation.
+	 *
+	 * @return void
+	 */
 	protected static function compute() {
 		// Calendar initialization
 		$nowYear = self::$now->format('Y');
@@ -69,18 +98,14 @@ class SupportedVersions
 	}
 
 	/**
-	 * Filtre qui sélectionne les branches qu'on souhaite afficher.
+	 * Filtre sélectionnant les données des branches à afficher.
 	 *
-	 * Par défaut, le filtre sélection les maintenues à la date courante,
-	 * c'est-à-dire les branches stable ou security.
+	 * Par défaut, récupère les branches affichables dans l'intervalle du calendrier
+	 * Sont affichables:
+	 * - Les branches avec une date de release initiale effective ou prévue antérieure à la date de fin de l'intervalle
+	 * - Les branches avec une date de fin postérieure à la date de début de l'intervalle ou non prévue
 	 *
-	 * le paramètre sert à inclure les branches non-maintenues dans la limite
-	 * des bornes sur calendrier
-	 *
-	 * les branches futures sont sélectionnées à condition qu'un date prévisionnelle de sortie existe
-	 * et qu'elle soit dans les limite des bornes du calendrier
-	 *
-	 * @param boolean $includeEol embed eol branches if true.
+	 * @param boolean $eol Ajoute les branches 'eol' à la sélection si true
 	 * @return array
 	 */
 	public static function branchesToShow($eol = false) {
@@ -117,6 +142,11 @@ class SupportedVersions
 		);
 	}
 
+	/**
+	 * Filtre sélectionnant les données des branches en fin de vie.
+	 *
+	 * @return array
+	 */
 	public static function eoledBranches() {
 		// @codeCoverageIgnoreStart
 		if (!self::$config) {
@@ -140,10 +170,22 @@ class SupportedVersions
 
 	//Calendar Part
 
+	/**
+	 * @internal Vérifie si l'intervalle de temps a une intersection avec le calendrier.
+	 *
+	 * @param DateTime $start
+	 * @param DateTime $end
+	 * @return bool
+	 */
 	protected static function inCalendar(DateTime $start, DateTime $end) {
 		return $start < self::$maxDate && $end >= self::$minDate;
 	}
 
+	/**
+	 * Filtre fournissant les années (format 'Y-m-d') composant le calendrier.
+	 *
+	 * @return void
+	 */
 	public static function years() {
 		// @codeCoverageIgnoreStart
 		if (!self::$config) {
@@ -154,6 +196,14 @@ class SupportedVersions
 		return self::$years;
 	}
 
+	/**
+	 * Filtre qui calcule la position horizontale d'une date dans le calendrier.
+	 *
+	 * @uses dateHorizCoord
+	 *
+	 * @param string $date une date au format 'Y-m-d'
+	 * @return int
+	 */
 	public static function horizCoord($date) {
 		// @codeCoverageIgnoreStart
 		if (!self::$config) {
@@ -249,6 +299,12 @@ class SupportedVersions
 		return $state;
 	}
 
+	/**
+	 * Filtre servant à calculer la coordonnées 'y' dans le calendrier pour une branche données.
+	 *
+	 * @param string $branch
+	 * @return void
+	 */
 	public static function top($branch) {
 		// @codeCoverageIgnoreStart
 		if (!self::$config) {
@@ -268,6 +324,9 @@ class SupportedVersions
 	}
 
 	/**
+	 * Filtre donnant la coordonnées 'y' du nom de la branche dans le calendrier.
+	 * Cf. modeles/supportedversions_calendar.html
+	 *
 	 * @codeCoverageIgnore
 	 *
 	 * @param string $branch
@@ -284,6 +343,9 @@ class SupportedVersions
 	}
 
 	/**
+	 * Filtre donnant la largeur du calendrier.
+	 * Cf. modeles/supportedversions_calendar.html
+	 *
 	 * @codeCoverageIgnore
 	 *
 	 * @param int $margin_left
@@ -300,6 +362,9 @@ class SupportedVersions
 	}
 
 	/**
+	 * Filtre donnant la hauteur du calendrier.
+	 * Cf. modeles/supportedversions_calendar.html
+	 *
 	 * @codeCoverageIgnore
 	 *
 	 * @param int $header_height

supportedversions_options.php

@@ -2,6 +2,11 @@
 
 // Sizing & Color constants.
 $GLOBALS['supportedversions'] = [
+	/**
+	 * Partie mise en forme du calendrier au format SVG en pixels.
+	 *
+	 * Cf. modeles/supportedversions_calendar.html
+	 */
 	'svg' => [
 		'margin_left' => 80,
 		'margin_right' => 50,
@@ -10,6 +15,12 @@ $GLOBALS['supportedversions'] = [
 		'branch_height' => 30,
 		'footer_height' => 24,
 	],
+	/**
+	 * Partie cosmétique pour CSS.
+	 *
+	 * Couleurs par défaut servant à mettre en évidence l'état de maintenance d'une version
+	 * Ce sont des couleurs atténuées par rapport à celles utilisées sur les sites php.net ou symfony.com
+	 */
 	'colors' => [
 		'future' => [
 			'background' => '#edcbdc',
@@ -25,6 +36,14 @@ $GLOBALS['supportedversions'] = [
 			'color' => 'white',
 		],
 	],
+	/**
+	 * Partie servant à définir la longueur du calendrier en années.
+	 *
+	 * @see https://www.php.net/manual/fr/datetime.formats.php
+	 *
+	 * min_year : intervalle en nombre d'années à afficher avant l'année courante
+	 * max_year : intervalle en nombre d'années à afficher à partir de l'année courante
+	 */
 	'calendar' => [
 		'min_year' => 'P3Y',
 		'max_year' => 'P5Y',