Aller au contenu principal

26-2 Documenter les classes générales (services et cie)

Documenter l'en-tête​

Pour documenter une classe, on commence par l'en-tête de la classe.

Pour écrire un bloc de commentaire, il est possible de commencer à taper /** soit devant ou juste à côté de ce qui est à commenter et appuyer sur enter. Cela créera automatiquement le bloc de commentaire.

Imgur

Ensuite, utilisez une description pertinente de la classe.

src/app/services/projet.service.ts
/**
 * Ce service permet d'effectuer les appels d'API pour les projets.
 */
@Injectable({
  providedIn: 'root'
})
export class ProjetService {

Documenter une fonction et son type de retour (@returns)​

Pour documenter une fonction, vous pouvez utiliser le même raccourci, soit commencer à taper /** et appuyer sur enter, à côté ou devant la fonction.

Cela inclura automatiquement le type de retour et la mention @returns:

src/app/services/projet.service.ts
/**
 * 
 * @returns {Promise<Projet[]>}
 */
async obtenirTous(): Promise<Projet[]>{
  let url = "/projets";
  let reponse = await api.get(url);
  let projets = reponse.data.records.map((record: any) => {
    return record.fields;
  });

  return projets;
}
info

@returns permet de documenter le retour. Vous pouvez mettre entre accolades ({}) le type de retour de la fonction.

Finalement, vous pouvez poursuivre en documentant le rôle de la fonction, ainsi que de donner plus de contexte sur le retour.

src/app/services/projet.service.ts
/**
 * Effectue la requête d'API permettant de retourner tous les projets.
 * @returns {Promise<Projet[]>} Promise représentant la liste des projets
 */
async obtenirTous(): Promise<Projet[]>{
  let url = "/projets";
  let reponse = await api.get(url);
  let projets = reponse.data.records.map((record: any) => {
    return record.fields;
  });

  return projets;
}

Documenter une fonction et ses paramètres (@param)​

Si vous avez une fonction avec des paramètres, WebStorm sera d'une grande aide encore pour préciser les paramètres dans la documentation.

src/app/services/projet.service.ts
/**
 * 
 * @param {string} id
 * @param {Projet} projet
 * @returns {Promise<Projet>}
 */
async modifier(id: string, projet: Projet): Promise<Projet> {
  let url = `/projets/${id}`;
  let requeteAirtable = {
    fields: projet
  };
  let reponse = await api.patch(url, requeteAirtable);

  return reponse.data.fields;
}
info

@param permet de définir un paramètre, avec le type entre accolades.

Comme pour le type de retour, documentez les paramètres.

src/app/services/projet.service.ts
/**
 * Effectue la requête d'API permettant de modifier un projet.
 * @param {string} id L'identifiant du projet à modifier
 * @param {Projet} projet Le projet modifié
 * @returns {Promise<Projet>} Promise représentant le projet modifié
 */
async modifier(id: string, projet: Projet): Promise<Projet> {
  let url = `/projets/${id}`;
  let requeteAirtable = {
    fields: projet
  };
  let reponse = await api.patch(url, requeteAirtable);

  return reponse.data.fields;
}