La documentation des clients est faite directement dans le code via TSDoc.
Cela permet d’avoir une documentation accessible directement dans l’IDE et de
faciliter la maintenance du code.
Structure de la Documentation
Client Principal
/**
* Client principal pour l'API Hubrise.
*
* Ce client permet d'interagir avec l'API Hubrise en fournissant des méthodes
* pour chaque domaine fonctionnel (orders, customers, etc.).
*
* @example
* ```typescript
* const client = new HubriseClient({
* baseUrl: "https://api.hubrise.com",
* apiKey: "your-api-key"
* });
*
* // Accès aux sous-clients
* const orders = client.orders;
* const customers = client.customers;
* ```
*/
export class HubriseClient {
// ... implementation
}
Sous-clients
/**
* Client pour la gestion des commandes Hubrise.
*
* Ce client permet d'interagir avec l'API des commandes Hubrise.
* Il fournit des méthodes pour créer, récupérer et mettre à jour les commandes.
*
* @example
* ```typescript
* // Création d'une commande
* const order = await client.orders.create({
* customerId: "123",
* items: [
* { name: "Pizza", quantity: 1 }
* ]
* });
*
* // Récupération d'une commande
* const order = await client.orders.get("order-id");
* ```
*/
export class HubriseOrderClient {
// ... implementation
}
Nouvelle Commande
/**
* Crée une nouvelle commande dans Hubrise.
*
* @param order - La commande à créer
* @returns La commande créée avec son ID Hubrise
* @throws {HubriseError} Si la création échoue
*
* @example
* ```typescript
* const order = await client.orders.create({
* customerId: "123",
* items: [
* { name: "Pizza", quantity: 1 }
* ]
* });
* ```
*/
async createOrder(order: Order): Promise<Order> {
// ... implementation
}
Commande par id
/**
- Récupère une commande par son ID.
-
- @param id - L'ID de la commande à récupérer
- @returns La commande trouvée
- @throws {HubriseError} Si la commande n'existe pas
-
- @example
- ```typescript
- const order = await client.orders.get("order-id");
- ```
*/
async getOrder(id: string): Promise<Order> {
// ... implementation
}
Mise a jour de la commande
/**
- Met à jour le statut d'une commande.
-
- @param id - L'ID de la commande à mettre à jour
- @param status - Le nouveau statut
- @returns La commande mise à jour
- @throws {HubriseError} Si la mise à jour échoue
-
- @example
- ```typescript
- const updatedOrder = await client.orders.updateStatus(
- "order-id",
- "preparing"
- );
-
*/
async updateOrderStatus(id: string, status: OrderStatus): Promise<Order> {
// ... implementation
}
}
Bonnes Pratiques
Documentation du Client Principal
• Description générale du client et son rôle• Exemple complet d’initialisation• Liste des sous-clients disponibles et leur utilité
Documentation des Sous-clients
• Description détaillée du domaine fonctionnel• Exemples d’utilisation courante avec du code• Liste exhaustive des méthodes disponibles
Documentation des Méthodes
• Description claire de la fonctionnalité• Documentation des paramètres et leur type• Spécification du type de retour• Liste des exceptions possibles• Exemples d’utilisation concrets
Exemples de Code
• Inclusion systématique d’exemples concrets• Démonstration des cas d’utilisation courants• Inclusion de la gestion des erreurs quand pertinent
Types et Interfaces
/**
* Configuration du client Hubrise.
*/
export interface HubriseClientConfig {
/** URL de base de l'API Hubrise */
baseUrl: string;
/** Clé API pour l'authentification */
apiKey: string;
}
/**
* Statuts possibles d'une commande Hubrise.
*/
export enum OrderStatus {
/** Commande en attente de confirmation */
PENDING = "pending",
/** Commande confirmée */
CONFIRMED = "confirmed",
/** Commande en préparation */
PREPARING = "preparing",
/** Commande prête */
READY = "ready",
/** Commande livrée */
DELIVERED = "delivered",
/** Commande annulée */
CANCELLED = "cancelled",
}
