Galactic-Shrine PHP Documentation Standard

Version: 1.2.0
Auteur / Author: ⋞Galactic-Shrine⋟
Portée / Scope: Projets PHP / Symfony / API / CLI / Bibliothèques internes

1. Objectif

Ce standard définit la manière de documenter le code PHP dans les projets Galactic-Shrine.

Il a pour objectifs :

d’uniformiser la documentation du code ;
de conserver un style bilingue [FR] / [EN] ;
de rester compatible avec les outils PHP modernes ;
de conserver un format visuel homogène ;
d’éviter les conventions C# non adaptées à PHP.

2. Principes généraux

La documentation PHP Galactic-Shrine doit être :

claire ;
concise ;
bilingue ;
standard ;
utile techniquement.

La documentation doit privilégier :

le format PHPDoc natif ;
les descriptions courtes ;
les tags PHPDoc standard ;
les types précis lorsqu’ils apportent une vraie valeur.

3. Format obligatoire des blocs

Toujours utiliser le format suivant :

/**
 * [FR] Génère les fichiers de traduction YAML.
 * [EN] Generates YAML translation files.
 */

Ne pas utiliser :

/** ... **/

4. Convention bilingue

Chaque description doit suivre l’ordre suivant :

ligne française [FR]
ligne anglaise [EN]

Exemple :

/**
 * [FR] Charge les locales configurées.
 * [EN] Loads the configured locales.
 */

5. Éléments autorisés

Éléments autorisés dans les commentaires PHPDoc Galactic-Shrine :

texte libre avec [FR] et [EN]
@param
@return
@throws
@var
@property
@method
@deprecated
@example
@see
@note

Éléments déconseillés ou interdits :

<summary>
<param>
<remarks>
<returns>
<exception>

Ces balises sont réservées aux conventions XML de type C# / C++ et ne doivent pas être utilisées en PHP.

6. Structure recommandée d’un commentaire

Ordre recommandé :

description courte [FR]
description courte [EN]
détail complémentaire [FR] si nécessaire
détail complémentaire [EN] si nécessaire
tags PHPDoc techniques

Exemple :

/**
 * [FR] Exécute la génération des traductions.
 * [EN] Executes translation generation.
 *
 * [FR] La méthode valide les entrées, exécute le traitement,
 *      puis retourne un code de sortie Symfony.
 * [EN] The method validates inputs, runs the process,
 *      then returns a Symfony exit code.
 *
 * @param InputInterface $input [FR] Entrée console.
 *                              [EN] Console input.
 * @param OutputInterface $output [FR] Sortie console.
 *                                [EN] Console output.
 * @return int [FR] Code de retour Symfony.
 *             [EN] Symfony return code.
 */

7. Standard par type d’élément

7.1 Classe

/**
 * [FR] Commande Symfony permettant de générer les fichiers de traduction YAML.
 * [EN] Symfony command used to generate YAML translation files.
 *
 * [FR] Cette commande s’appuie sur la commande native de Symfony
 *      et ajoute une logique métier complémentaire.
 * [EN] This command relies on Symfony's native command
 *      and adds complementary business logic.
 */
final class GenerateLangCommand extends Command
{
}

7.2 Propriété

/**
 * @var array<int, string>|string [FR] Locales configurées.
 *                                [EN] Configured locales.
 */
private readonly array|string $appLocales;

7.3 Constructeur

/**
 * [FR] Initialise une nouvelle instance de la classe.
 * [EN] Initializes a new instance of the class.
 *
 * @param string $projectDir [FR] Répertoire racine du projet.
 *                           [EN] Project root directory.
 * @param array<int, string>|string $appLocales [FR] Locales configurées.
 *                                              [EN] Configured locales.
 */
public function __construct(string $projectDir, array|string $appLocales)
{
}

7.4 Méthode simple

/**
 * [FR] Normalise une liste de valeurs.
 * [EN] Normalizes a list of values.
 *
 * @param array<int, string>|string|null $values [FR] Valeurs d’entrée.
 *                                               [EN] Input values.
 * @return list<string> [FR] Valeurs normalisées.
 *                      [EN] Normalized values.
 */
private function normalizeValues(array|string|null $values): array
{
}

7.5 Méthode métier

/**
 * [FR] Exécute le traitement principal de la commande.
 * [EN] Executes the main command processing.
 *
 * [FR] La méthode valide les entrées, prépare les dépendances,
 *      lance le traitement puis retourne un code de sortie Symfony.
 * [EN] The method validates inputs, prepares dependencies,
 *      runs the process, then returns a Symfony exit code.
 *
 * @param InputInterface $input [FR] Entrée console.
 *                              [EN] Console input.
 * @param OutputInterface $output [FR] Sortie console.
 *                                [EN] Console output.
 * @return int [FR] Code de retour Symfony.
 *             [EN] Symfony return code.
 */
protected function execute(InputInterface $input, OutputInterface $output): int
{
}

7.6 Méthode avec exception

/**
 * [FR] Écrit les données dans un fichier YAML.
 * [EN] Writes data into a YAML file.
 *
 * @param string $filePath [FR] Chemin du fichier.
 *                         [EN] File path.
 * @param array<string, mixed> $data [FR] Données à écrire.
 *                                   [EN] Data to write.
 * @throws \RuntimeException [FR] Si l’écriture échoue.
 *                           [EN] If writing fails.
 */
private function writeYamlFile(string $filePath, array $data): void
{
}

7.7 Méthode récursive ou technique

/**
 * [FR] Parcourt récursivement un tableau pour collecter les entrées terminales.
 * [EN] Recursively walks an array to collect terminal entries.
 *
 * @param array<string, mixed> $data [FR] Données à parcourir.
 *                                   [EN] Data to traverse.
 * @param list<string> $path [FR] Chemin courant.
 *                           [EN] Current path.
 * @return list<array{id:string, path:list<string>, value:mixed}> [FR] Entrées collectées.
 *                                                                [EN] Collected entries.
 */
private function collectEntries(array $data, array $path = []): array
{
}

8. Règles de style

8.1 Descriptions courtes

Toujours préférer une phrase simple et directe.

8.2 Ordre fixe

Toujours écrire [FR] avant [EN].

8.3 Tags techniques compacts

Écrire les tags sur une seule ligne lorsque c’est lisible. Utiliser plusieurs lignes si cela améliore la lisibilité.

8.4 `@return`

Documenter @return lorsqu’il existe une vraie valeur de retour. Ne pas écrire @return void sauf besoin particulier d’uniformité stricte.

8.5 `@throws`

N’ajouter @throws que si l’information est importante pour l’appelant.

8.6 Pas de surdocumentation

Ne pas commenter l’évidence.

9. Types d’éléments à documenter en priorité

Documenter en priorité :

classes de service ;
commandes Symfony ;
écouteurs, subscribers et composants techniques ;
méthodes publiques ;
méthodes complexes ;
propriétés dont le rôle ou le type n’est pas trivial ;
structures de données documentaires ;
API internes importantes.

10. Exemple complet recommandé

<?php

declare(strict_types=1);

namespace App\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * [FR] Génère les fichiers de traduction YAML pour les locales configurées.
 * [EN] Generates YAML translation files for configured locales.
 *
 * [FR] Cette commande s’appuie sur la commande native de Symfony
 *      et ajoute une logique de filtrage et de nettoyage.
 * [EN] This command relies on Symfony's native command
 *      and adds filtering and cleanup logic.
 */
final class GenerateLangCommand extends Command
{
    /**
     * @var array<int, string>|string [FR] Locales configurées.
     *                                [EN] Configured locales.
     */
    private readonly array|string $appLocales;

    /**
     * [FR] Initialise la commande.
     * [EN] Initializes the command.
     *
     * @param array<int, string>|string $appLocales [FR] Locales configurées.
     *                                              [EN] Configured locales.
     * @param string $projectDir [FR] Répertoire racine du projet.
     *                           [EN] Project root directory.
     */
    public function __construct(
        array|string $appLocales,
        private readonly string $projectDir,
    ) {
        parent::__construct();
        $this->appLocales = $appLocales;
    }

    /**
     * [FR] Exécute la génération des traductions.
     * [EN] Executes translation generation.
     *
     * @param InputInterface $input [FR] Entrée console.
     *                              [EN] Console input.
     * @param OutputInterface $output [FR] Sortie console.
     *                                [EN] Console output.
     * @return int [FR] Code de retour Symfony.
     *             [EN] Symfony return code.
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        return Command::SUCCESS;
    }
}

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine PHP :

utiliser /** ... */ ;
écrire d’abord [FR], puis [EN] ;
utiliser uniquement des balises PHPDoc natives ;
utiliser @param, @return, @throws, @var lorsque cela apporte une vraie valeur ;
ne pas importer les conventions XML C# / C++ ;
documenter ce qui compte, pas l’évidence.

12. Résumé exécutable

À appliquer dans tous les projets PHP Galactic-Shrine :

utiliser PHPDoc natif ;
écrire [FR] puis [EN] ;
documenter les classes, méthodes et structures réellement utiles ;
garder un style court, propre et uniforme ;
éviter les commentaires inutiles sur le code trivial.

Galactic-Shrine PHP Documentation Standard

Galactic-Shrine PHP Documentation Standard

1. Objectif

2. Principes généraux

3. Format obligatoire des blocs

4. Convention bilingue

5. Éléments autorisés

6. Structure recommandée d’un commentaire

7. Standard par type d’élément

7.1 Classe

7.2 Propriété

7.3 Constructeur

7.4 Méthode simple

7.5 Méthode métier

7.6 Méthode avec exception

7.7 Méthode récursive ou technique

8. Règles de style

8.1 Descriptions courtes

8.2 Ordre fixe

8.3 Tags techniques compacts

8.4 @return

8.5 @throws

8.6 Pas de surdocumentation

9. Types d’éléments à documenter en priorité

10. Exemple complet recommandé

11. Décision officielle recommandée

12. Résumé exécutable

8.4 `@return`

8.5 `@throws`