Comprendre la notation

Dans la documentation discord.js et lors de la demande d'aide sur le serveur officiel, vous rencontrerez de nombreuses sortes de notations différentes. Pour vous aider à comprendre les textes que vous lisez, nous allons passer en revue certaines notations standard.

Classes

Certaines notations courantes se réfèrent à une classe ou aux propriétés, méthodes ou événements d'une classe. Il existe de nombreuses variations de ces notations, et elles sont très flexibles selon la personne, donc utilisez votre jugement en les lisant.

La notation <Class> signifie une instance de la classe Class. Par exemple, un extrait comme <BaseInteraction>.reply('Hello') vous demande de remplacer <BaseInteraction> par une valeur qui est une instance de BaseInteraction, par exemple interaction.reply('Hello'). Cela pourrait aussi être simplement un espace réservé, par exemple <id> signifierait un espace réservé pour un ID.

La notation Class#foo peut faire référence à la propriété foo, à la méthode ou à l'événement de la classe Class. Lequel l'auteur voulait dire doit être déterminé en fonction du contexte. Par exemple :

• BaseInteraction#user signifie que vous devriez faire référence à la propriété user sur un BaseInteraction.
• TextChannel#send signifie que vous devriez faire référence à la méthode send sur un TextChannel.
• Client#interactionCreate signifie que vous devriez faire référence à l'événement interactionCreate sur un Client.

Parfois, la notation est étendue, ce qui peut vous aider à déterminer ce que l'auteur voulait dire. Par exemple, TextChannel#send(options) est définitivement une méthode de TextChannel, puisqu'elle utilise la notation de fonction. Client#event:messageCreate est un événement puisqu'il le dit.

La chose vitale à retenir de cette notation est que le symbole # signifie que la propriété, la méthode ou l'événement ne peut être accédé que par une instance de la classe. Malheureusement, beaucoup abusent de cette notation, par exemple <Message>#send ou Util#resolveColor. <Message> est déjà une instance, cela n'a donc aucun sens, et resolveColor est une méthode statique - vous devriez l'écrire comme Util.resolveColor. Reportez-vous toujours à la documentation si vous êtes confus.

Par exemple, la fonctionnalité de recherche de la documentation utilise cette notation.

Notez l'utilisation de l'opérateur . pour la méthode statique, Role.comparePositions et la notation # pour la méthode, Role#comparePositionsTo.

Types

Dans la documentation discord.js, il y a des signatures de type partout, comme dans les propriétés, les paramètres ou les valeurs de retour. Si vous ne venez pas d'un langage typé statiquement, vous ne savez peut-être pas ce que certaines notations signifient.

Le symbole * signifie n'importe quel type. Par exemple, les méthodes qui retournent * signifient qu'elles peuvent retourner n'importe quoi, et un paramètre de type * peut être n'importe quoi.

Le symbole ? signifie que le type est nullable. Vous pouvez le voir avant ou après le type (par exemple ?T ou T?). Ce symbole signifie que la valeur peut être du type T ou null. Un exemple est GuildMember#nickname ; son type est ?string puisqu'un membre peut ou non avoir un surnom.

L'expression T[] signifie un tableau de T. Vous pouvez parfois voir plusieurs crochets [], indiquant que le tableau est multidimensionnel, par exemple string[][].

L'expression ...T signifie un paramètre rest de type T. Cela signifie que la fonction peut prendre n'importe quel nombre d'arguments, et tous ces arguments doivent être du type T.

L'opérateur |, qui peut se lire comme "ou", crée un type union, par exemple A|B|C. Simplement, cela signifie que la valeur peut être l'un des types donnés.

Les crochets angulaires <> sont utilisés pour les types génériques ou les types paramétrés, signifiant un type qui utilise un ou plusieurs type(s). La notation ressemble à A<B> où A est le type et B est un paramètre de type. Si c'est difficile à suivre, il suffit de garder à l'esprit que chaque fois que vous voyez A<B>, vous pouvez penser à un A contenant B. Exemples :

• Array<String> signifie un tableau de chaînes.
• Promise<User> signifie une Promise qui contient un User.
• Array<Promise<User|GuildMember>> serait un tableau de Promises, chacun contenant un User ou un GuildMember.
• Collection<Snowflake, User> serait une Collection, contenant des paires clé-valeur où les clés sont des Snowflakes et les valeurs sont des Users.

Dans cette partie de la documentation, vous pouvez voir deux signatures de type, string, MessagePayload ou MessageOptions, et Promise<(Message|Array<Message>)>. Le sens du mot "ou" ici est le même que |.