Documentation des variables d'environnement

Le JSDoc au-dessus de chaque propriété @Env('...') est exporté presque textuellement dans la référence des variables d'environnement sur docs.n8n.io. Le tableau généré a quatre colonnes : nom de la variable, description, type de données, valeur par défaut. Votre JSDoc est la colonne description. Le lecteur est un opérateur en auto-hébergement, pas un développeur n8n.

Suivez le guide de style de la documentation n8n pour ces commentaires. Il remplace la règle ASD-STE100 de AGENTS.md dans ce seul cas. Les règles ci-dessous sont les parties de ce guide qui importent pour une description d'un paragraphe.

Règles

• Chaque propriété @Env a un JSDoc. Pas d'exceptions. Un commentaire manquant s'affiche comme une cellule de description vide.
• Écrivez pour l'opérateur. Dites ce que fait le paramètre, quand le modifier, et ce qui se passe quand il n'est pas défini ou est incorrect. N'expliquez pas pourquoi le code est écrit de cette façon.
• Pas de références au code. Pas de noms de fichiers, de classes, de fonctions, de constantes, de clés de licence ou d'autres détails internes que le lecteur ne peut pas consulter. Les valeurs que l'opérateur tape dans la variable sont correctes et souvent nécessaires, par exemple un ID de type de credential comme googleOAuth2Api ou un mode comme postgresdb. Le test : l'opérateur collerait-il cela dans un fichier de configuration, ou aurait-il besoin du code source pour savoir ce que ça signifie ? Les détails pour les développeurs vont dans un commentaire // ordinaire sur l'implémentation, pas dans le JSDoc.
• Pas de scénarios d'attaque. Dites ce que le paramètre protège, pas comment un attaquant l'exploiterait. C'est une page publique.
• Ne répétez pas la valeur par défaut. La valeur par défaut s'affiche dans sa propre colonne. N'écrivez pas « La valeur par défaut est true » ou « Valeur par défaut : 1 heure ». Dites ce que l'état non défini signifie quand ce n'est pas évident, par exemple « Quand elle n'est pas définie, n8n utilise l'hôte Redis ».
• Indiquez les unités et les formats. Dites « en millisecondes », « en octets », « une liste séparée par des virgules », « un objet JSON ». La colonne de type de données ne dit que Number ou String.
• Utilisez les valeurs autorisées quand l'ensemble est petit. « L'une de sqlite, postgresdb. » Pour une liste, montrez un exemple inline dans la phrase.
• Pas de balises JSDoc. Pas de @example, @default, @see, @deprecated. L'exportateur copie le nom de la balise dans la documentation. Mettez l'exemple ou l'avis de dépréciation dans une phrase à la place.
• Noms de produits : « Gateway credits », pas « n8n Connect » ou « AI Gateway ». « Publish a workflow », pas « activate ». n8n est toujours minuscule.
• Style : présent, voix active, deuxième personne. Utilisez des contractions. Pas de tirets cadratins, utilisez une virgule ou une nouvelle phrase. Pas de « par exemple » ou « c'est-à-dire », écrivez « for example » et « that is ». Écrivez en toutes lettres zéro à neuf, en chiffres à partir de 10. Les valeurs que l'opérateur tape restent des chiffres, par exemple « Set to 0 ». Casse de titre. Une idée par phrase. Terminez chaque phrase par un point.
• Mots simples : « use » au lieu de « utilize », « lets you » au lieu de « allows you to », supprimez « powerful », « seamless », « simply », « it's important to note ».
• Longueur : une à trois phrases. Si le paramètre en demande plus, le reste appartient à une page de documentation que le commentaire ne peut pas encore lier ; gardez le commentaire à ce qui tient dans une cellule de tableau.

Exemples

Mauvais, tel que trouvé dans la documentation générée :

/**
 * Instance-level enablement for n8n Connect (AI Gateway). Licensed instances
 * are enabled by default; false opts out. Budget / free allowance still comes
 * from the license (`quota:aiGatewayBudget`).
 */

Mauvais nom de produit, une valeur par défaut réaffirmée, et une clé de licence interne. Bon :

/**
 * Whether Gateway credits are available on this instance. Set to false to
 * turn them off on a licensed instance. The credit allowance comes from your
 * license.
 */

Mauvais :

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to disable
 * expiry. Default: 1 hour.
 */

La valeur par défaut est déjà dans le tableau. Bon :

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to keep
 * entries until Redis evicts them.
 */

Mauvais :

/**
 * Comma-separated list of credential types for which overwrites are skipped
 * when the credential has been customized.
 * @example `N8N_SKIP_CREDENTIAL_OVERWRITE=zohoOAuth2Api,salesforceOAuth2Api`
 */

La balise @example s'affiche dans la description comme du texte littéral. Bon :

/**
 * Comma-separated list of credential types to skip when applying credential
 * overwrites, for example `zohoOAuth2Api,salesforceOAuth2Api`. n8n skips an
 * overwrite only when a user has already changed one of its fields.
 */

Mauvais :

/**
 * Bind OAuth credential callbacks to the browser that initiated the flow.
 * When enabled, a session-scoped `n8n-oauth-binding` cookie is set on flow
 * initiation and verified on callback. Defeats phishing attacks where an
 * attacker injects an OAuth authorize URL into a victim's browser to land
 * tokens on the attacker's credential.
 */

Récit d'attaque et un nom de cookie interne sur une page publique. Bon :

/**
 * Whether an OAuth credential connection must finish in the same browser
 * that started it. When enabled, n8n rejects the callback if it arrives
 * from a different browser.
 */

Liste de contrôle de relecture

Quand vous relisez une PR qui ajoute ou modifie une propriété @Env, vérifiez chaque commentaire par rapport à cette liste et citez la correction dans la relecture :

1. JSDoc présent.
2. Pas d'identifiants de code, de noms de fichiers ou de clés internes.
3. Pas de valeur par défaut réaffirmée.
4. Unités, format ou valeurs autorisées indiqués.
5. Pas de balises JSDoc.
6. Pas de tirets cadratins, d'abréviations latines ou de mots de remplissage.
7. Se lit correctement comme une phrase dans une cellule de tableau sans contexte environnant.