# Come documentare i componenti

Documentare un componente significa scrivere API, stati e limiti in un formato leggibile senza aprire il codice. La struttura che regge, con i numeri del catalogo EneUI.

> Pagina: https://ui.eneawork.it/blog/come-documentare-i-componenti
> Markdown: https://ui.eneawork.it/blog/come-documentare-i-componenti.md

*2026-11-01*

Documentare un componente significa scrivere la sua API, i suoi stati e i suoi limiti in un formato che un altro sviluppatore legge senza aprire il codice. Non è un commento nel file, non è uno screenshot e non è una pagina di catalogo.

Il catalogo EneUI conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, misurati e letti da /api/stats il 1 novembre 2026. Sui 1.556 blocchi, 403 (25,9%) hanno sia una descrizione sia una categoria, 114 (7,3%) non hanno descrizione e 1.072 (68,9%) non hanno categoria: conteggio eseguito il 1 novembre 2026 su data/blocks.json, snapshot del 31 ottobre 2026. La misura riguarda i metadati del catalogo, non la qualità del codice.

## Le cinque parti di una scheda

Una scheda utile risponde a cinque domande, sempre nello stesso ordine. Se ne manca una, il lettore torna a leggere il codice.

## Il comando: estrarre i tipi

npx react-docgen src/components/Button.tsx

react-docgen è un progetto MIT: legge i tipi TypeScript e i valori predefiniti e restituisce JSON. Ti dà la tabella delle props in automatico; non ti dà la frase che spiega a cosa serve il componente, e quella resta da scrivere.

## Un record che documenta bene

Nel catalogo, zoomable image di Fumadocs mostra descrizione, dipendenze, licenza a monte e comando di installazione nello stesso posto. La libreria è Fumadocs, licenza MIT, e il record si raggiunge anche dall'indice dei 111.985 componenti.

## La limitazione

Nessuno strumento verifica che la documentazione sia vera. react-docgen estrae i tipi, non i comportamenti: un componente documentato male supera ogni test e ogni lint, e la scheda sbagliata resta online.

## Dove continuare

Il formato di un record installabile è in che cos'è un registry. Per le sezioni di una pagina di documentazione leggi blocchi per la documentazione; il confronto tra codice copiato e libreria è in copy-paste o headless.

## FAQ

### Cosa deve contenere la documentazione di un componente?

Scopo in una frase, props con tipo e valore predefinito, stati visivi, contratto da tastiera e ARIA, limiti dichiarati. Se una di queste parti manca, il lettore deve aprire il codice.

### Basta un commento nel codice sorgente?

No. Un commento spiega una scelta a chi già conosce il file; la documentazione serve a chi non lo conosce. Il commento resta utile, ma non sostituisce la scheda.

### Serve Storybook per documentare i componenti?

No. Storybook è uno strumento MIT utile per gli stati interattivi, ma una pagina statica con props e immagini degli stati copre la maggior parte dei casi.

### Come documento gli stati di un componente?

Un esempio per ogni stato, con lo stesso contenuto: default, hover, focus, disabled, loading, errore. La differenza tra gli esempi deve essere solo lo stato.

### Chi scrive la documentazione?

Chi scrive il componente, prima di aprire la pull request. La documentazione scritta dopo, da un'altra persona, descrive ciò che il codice fa e non ciò che dovrebbe fare.