Théorie Documentation application Vue

La syntaxe de documentation dans Vue est la suivante : /** */.

Par exemple :

/**
 * Retourne la somme de deux nombres.
 * @param a - Le premier nombre
 * @param b - Le deuxième nombre
 * @returns La somme de a et b
 */
function addition(a: number, b: number): number {
  return a + b;
}

Documenter les composants

Fonctions

La syntaxe /** */ est celle de JSDocs, vu précédemment cette session. Nous allons pouvoir la réutiliser!

/**
 * Gère la soumission du formulaire
 * @returns {Promise<void>}
 */
async function soumettre(){
  const requete: CreerCommandeRequete = {
    client: nomClient.value,
    recette_id: recetteId.value!
  }

  const commande = await commandeService.creerCommande(requete);
  await router.push(`/commandes/${commande.id}`);
}

Information ❗

Vous n'avez pas à commencer votre documentation par Fonction qui.... On le sait qu'il s'agit d'une fonction 😃 Allez immédiatement dans son rôle et l'action qu'elle effectue ou gère.

Information ❗

Vous n'avez pas à documenter les fonctions en provenance de Vue comme onMounted par exemple.

Variables

Pour documenter les variables, nous allons simplement utiliser la syntaxe /** */ au-dessus de la variable. Par exemple :

/**
 * Le nom du client qui passe la commande
 */
const nomClient = ref('');

Documenter les services

On va utiliser les JSDocs pour documenter les fonctions de nos services. Cela doit inclure les paramètres et la sortie de la fonction.

/**
 * Modifie une commande
 * @param {string} id L'identifiant de la commande
 * @param {ModifierCommandeRequete} requete Les données modifiées à soumettre
 * @returns {Promise<Commande>} La commande modifiée
 */
async modifierCommande(id: string, requete: ModifierCommandeRequete): Promise<Commande> {
  const url = `/etudiants/1212121/commandes/${id}`;
  const reponse = await api.patch<Commande>(url, requete);

  return reponse.data;
}

Documenter les modèles (typings)

Pour documenter les modèles, documentez simplement les propriétés via /** */, en plus de l'en-tête de l'interface.

/**
* Une commande client
*/
export interface Commande {
  /**
   * Identifiant de la commande
   */
  id: number;
  /**
   * Nom du client
   */
  client: string;
  /**
   * Recette associée à la commande
   */
  recette: Recette;
  /**
   * Date de création
   */
  created_at: string;
  /**
   * Date de modification
   */
  updated_at: string;
}

Il est possible de faire une version abrégée des commentaires en une seule ligne :

/**
* Une commande client
*/
export interface Commande {
  /** Identifiant de la commande */
  id: number;
  
  /** Nom du client */
  client: string;
  
  /** Recette associée à la commande */
  recette: Recette;
  
  /** Date de création */
  created_at: string;
  
  /** Date de modification */
  updated_at: string;
}