Warning
In caso di dubbi sulla correttezza del contenuto di questa traduzione, l’unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le avvertenze.
Come contribuire al miglioramento della documentazione del kernel¶
La documentazione è una parte importante di ogni progetto di sviluppo software. Una buona documentazione aiuta ad attirare nuovi sviluppatori e permette a quelli già presenti di lavorare in modo più efficace. Senza una documentazione di qualità, si spreca molto tempo nel decifrare il codice a ritroso e si commettono errori altrimenti evitabili.
Sfortunatamente, al momento la documentazione del kernel è ben lontana da quello che dovrebbe essere per sostenere un progetto di queste dimensioni e importanza.
Questa guida è per chi vuole contribuire a migliorare questa situazione. I miglioramenti alla documentazione del kernel possono essere fatti da sviluppatori con diversi livelli di esperienza; sono un modo relativamente semplice per imparare il processo di sviluppo del kernel in generale e trovare il proprio posto nella comunità. Quello che segue è, per la maggior parte, l’elenco dei compiti che il manutentore della documentazione ritiene più urgenti.
Le cose da fare nella documentazione¶
C’è un elenco infinito di compiti da svolgere per portare la nostra documentazione al livello in cui dovrebbe essere. Questo elenco contiene alcuni punti importanti, ma è lungi dall’essere esaustivo; se trovate un modo diverso per migliorare la documentazione, non esitate!
Correzione degli avvisi¶
Al momento, la generazione della documentazione produce un numero incredibile di avvisi. Quando ce ne sono così tanti, è come se non ce ne fosse nessuno: le persone li ignorano e non si accorgeranno mai quando il loro lavoro ne aggiunge di nuovi. Per questo motivo, eliminare gli avvisi è uno dei compiti a più alta priorità nell’elenco delle cose da fare per la documentazione. Il compito in sé è ragionevolmente semplice, ma va affrontato nel modo giusto per avere successo.
Gli avvisi emessi da un compilatore per il codice C possono spesso essere scartati come falsi positivi, portando a patch il cui unico scopo è zittire il compilatore. Gli avvisi generati dalla documentazione, invece, indicano quasi sempre un problema reale; farli sparire richiede di comprendere il problema e correggerlo alla radice. Per questo motivo, le patch che correggono avvisi nella documentazione non dovrebbero limitarsi a dire “fix a warning” nel titolo del changelog; dovrebbero invece indicare il problema reale che è stato corretto.
Un altro punto importante è che gli avvisi nella documentazione sono spesso generati da problemi nei commenti kerneldoc all’interno del codice C. Anche se il manutentore della documentazione apprezza l’essere messo in copia sulle correzioni di questo tipo, in realtà spesso rivolgersi al sottosistema di documentazione non è il modo migliore di apportare queste modifiche; queste dovrebbero invece essere inviate al manutentore del sottosistema in questione.
Per esempio, in una generazione della documentazione ho preso, quasi a caso, un paio di avvisi:
./drivers/devfreq/devfreq.c:1818: warning: bad line:
- Resource-managed devfreq_register_notifier()
./drivers/devfreq/devfreq.c:1854: warning: bad line:
- Resource-managed devfreq_unregister_notifier()
(Le righe sono state divise per essere più leggibili).
Una rapida occhiata al file sorgente indicato sopra ha rivelato un paio di commenti kerneldoc con questo aspetto:
/**
* devm_devfreq_register_notifier()
- Resource-managed devfreq_register_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
* @list: DEVFREQ_TRANSITION_NOTIFIER.
*/
Il problema è l’asterisco mancante, che confonde l’idea semplicistica che il
sistema di generazione abbia idea di come debba essere fatto un blocco di
commento C. Questo problema era presente fin da quando quel commento venne
aggiunto nel 2016, quindi da diversi anni. Correggerlo è stata solo questione di
aggiungere gli asterischi mancanti. Una rapida occhiata alla cronologia di quel
file ha mostrato quale fosse il formato usuale per la riga dell’oggetto, e
scripts/get_maintainer.pl mi ha detto chi dovesse riceverla (basta passare
il percorso delle vostre patch come argomento a scripts/get_maintainer.pl). La
patch risultante era questa:
[PATCH] PM / devfreq: Fix two malformed kerneldoc comments
Two kerneldoc comments in devfreq.c fail to adhere to the required format,
resulting in these doc-build warnings:
./drivers/devfreq/devfreq.c:1818: warning: bad line:
- Resource-managed devfreq_register_notifier()
./drivers/devfreq/devfreq.c:1854: warning: bad line:
- Resource-managed devfreq_unregister_notifier()
Add a couple of missing asterisks and make kerneldoc a little happier.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
drivers/devfreq/devfreq.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
index 57f6944d65a6..00c9b80b3d33 100644
--- a/drivers/devfreq/devfreq.c
+++ b/drivers/devfreq/devfreq.c
@@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
/**
* devm_devfreq_register_notifier()
- - Resource-managed devfreq_register_notifier()
+ * - Resource-managed devfreq_register_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
@@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
/**
* devm_devfreq_unregister_notifier()
- - Resource-managed devfreq_unregister_notifier()
+ * - Resource-managed devfreq_unregister_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
--
2.24.1
L’intero procedimento ha richiesto solo pochi minuti. Naturalmente, ho poi scoperto che qualcun altro l’aveva già corretto in un altro albero, mettendo in luce un’altra lezione: controllate sempre linux-next per vedere se un problema è già stato risolto prima di mettervici sopra.
Altre correzioni richiederanno più tempo, specialmente quelle relative ai campi di una struttura o ai parametri di una funzione privi di documentazione. In questi casi, è necessario capire quale sia il ruolo di questi campi o parametri e descriverli correttamente. Nel complesso, questo compito diventa un po’ tedioso a volte, ma è molto importante. Se riusciamo davvero ad eliminare gli avvisi dalla generazione della documentazione, allora potremo iniziare a pretendere che gli sviluppatori evitino di aggiungerne di nuovi.
Oltre ai normali avvisi durante la generazione della documentazione, potete
ottenerne di più eseguendo make refcheckdocs per trovare riferimenti a file
di documentazione inesistenti.
Commenti kerneldoc dimenticati¶
Gli sviluppatori sono incoraggiati a scrivere commenti kerneldoc per il
loro codice, ma molti di questi commenti non vengono mai inclusi nella
generazione della documentazione. Questo rende tale informazione più
difficile da trovare e, per esempio, impedisce a Sphinx di generare
collegamenti verso quella documentazione. Aggiungere le direttive
kernel-doc alla documentazione per includere quei commenti può aiutare
la comunità a ottenere il pieno valore del lavoro speso per crearli.
Lo strumento tools/docs/find-unused-docs.sh può essere usato per
trovare questi commenti dimenticati.
Da notare che il valore maggiore deriva dall’includere la documentazione per le funzioni e le strutture dati esportate. Molti sottosistemi hanno anche commenti kerneldoc per uso interno; questi non dovrebbero essere inclusi nella generazione della documentazione a meno che non vengano posti in un documento specificamente rivolto agli sviluppatori che lavorano all’interno del sottosistema in questione.
Correzione dei refusi¶
Correggere errori di battitura o di formattazione nella documentazione è un modo rapido per imparare come creare e inviare patch, ed è un servizio utile. Sono sempre disposto ad accettare questo tipo di patch. Detto questo, una volta che ne avete corretti alcuni, considerate di passare a compiti più avanzati, lasciando qualche refuso per il prossimo principiante che vorrà occuparsene.
Da notare che alcune cose non sono refusi e non dovrebbero essere “corrette”:
Sia la grafia americana che quella britannica dell’inglese sono ammesse nella documentazione del kernel. Non c’è bisogno di sostituire l’una con l’altra.
La questione se un punto debba essere seguito da uno o due spazi non va dibattuta nel contesto della documentazione del kernel. Anche altri argomenti di legittimo disaccordo, come la “virgola di Oxford”, non sono pertinenti qui.
Come per qualsiasi patch a qualsiasi progetto, considerate se la vostra modifica sta davvero migliorando le cose.
Documentazione datata¶
Parte della documentazione del kernel è attuale, mantenuta e utile. Un’altra parte... non lo è. Documentazione impolverata, vecchia e imprecisa può fuorviare i lettori e gettare discredito sulla nostra documentazione nel suo complesso. Qualsiasi cosa si possa fare per affrontare questi problemi è più che benvenuta.
Ogni volta che lavorate su un documento, considerate se è attuale, se ha bisogno di essere aggiornato, o se forse dovrebbe essere rimosso del tutto. Ci sono alcuni segnali d’allarme a cui potete prestare attenzione:
Riferimenti a kernel della serie 2.x
Rimandi a repositori su SourceForge
Nella cronologia, negli ultimi anni, solo correzioni di refusi
Discussioni su modi di lavorare precedenti a Git
La cosa migliore da fare, ovviamente, sarebbe portare la documentazione a essere attuale, aggiungendo qualsiasi informazione necessaria. Un lavoro simile spesso richiede la collaborazione di sviluppatori che conoscono bene il sottosistema in questione. Gli sviluppatori, quando viene chiesto loro gentilmente, e quando le loro risposte vengono ascoltate e messe in pratica, sono spesso più che disposti a collaborare con chi lavora per migliorare la documentazione.
Alcuni documenti sono senza speranza; a volte troviamo documenti che fanno riferimento a codice rimosso dal kernel molto tempo fa, per esempio. C’è una sorprendente resistenza a rimuovere la documentazione obsoleta, ma dovremmo farlo comunque. Il materiale superfluo nella nostra documentazione non è d’aiuto a nessuno.
Nei casi in cui, forse, ci sono informazioni utili in un documento gravemente datato, e non siete in grado di aggiornarlo, la cosa migliore da fare potrebbe essere aggiungere un avviso all’inizio. Si raccomanda il seguente testo:
.. warning ::
This document is outdated and in need of attention. Please use
this information with caution, and please consider sending patches
to update it.
In questo modo, almeno i nostri pazientissimi lettori sono stati avvisati che il documento potrebbe portarli fuori strada.
Coerenza della documentazione¶
I veterani di qui ricorderanno i libri su Linux che comparvero sugli scaffali negli anni ‘90. Erano semplicemente raccolte di file di documentazione racimolati da varie fonti in rete. I libri sono (per lo più) migliorati da allora, ma la documentazione del kernel è ancora per lo più costruita su quel modello. Sono migliaia di file, quasi ognuno dei quali è stato scritto in isolamento da tutti gli altri. Non abbiamo un corpo coerente di documentazione del kernel; abbiamo migliaia di documenti individuali.
Abbiamo cercato di migliorare la situazione creando un insieme di “libri” che raggruppano la documentazione per specifici lettori. Questi includono:
Così come questo libro sulla documentazione stessa.
Spostare i documenti nei libri appropriati è un compito importante e deve continuare. Ci sono, tuttavia, un paio di sfide associate a questo lavoro. Spostare i file della documentazione, nel breve termine, infastidisce chi vi lavora; comprensibilmente, non sono entusiasti di questi cambiamenti. Di solito li si può convincere a spostarli una volta; tuttavia, non vogliamo continuare a spostarli in giro.
Anche quando tutti i documenti sono al posto giusto, però, siamo solo riusciti a trasformare un grande cumulo in un gruppo di cumuli più piccoli. Il lavoro di cercare di tessere insieme tutti quei documenti in un unico insieme non è ancora iniziato. Se avete idee brillanti su come potremmo procedere su questo fronte, saremmo più che felici di sentirle.
Miglioramenti al foglio di stile¶
Con l’adozione di Sphinx abbiamo un output HTML dall’aspetto molto più gradevole di quanto avessimo un tempo. Ma è ancora migliorabile; Donald Knuth e Edward Tufte non ne sarebbero impressionati. Questo richiede di modificare i nostri fogli di stile per creare un output tipograficamente più solido, accessibile e leggibile.
Attenzione: se vi assumete questo compito, vi state addentrando nel classico territorio del “bikeshed”. Aspettatevi molte opinioni e discussioni anche per cambiamenti relativamente ovvi. Questa è, ahimè, la natura del mondo in cui viviamo.
Generazione di PDF senza LaTeX¶
Questo è un compito decisamente non banale per qualcuno con molto tempo a disposizione e competenze in Python. La catena di strumenti di Sphinx è relativamente piccola e ben contenuta; è facile da aggiungere a un sistema di sviluppo. Ma generare output in PDF o EPUB richiede l’installazione di LaTeX, che non è affatto piccolo o ben contenuto. Sarebbe una bella cosa da eliminare.
La speranza originale era di usare lo strumento rst2pdf (https://rst2pdf.org/) per la generazione dei PDF, ma si è scoperto che non era all’altezza del compito. Il lavoro di sviluppo su rst2pdf sembra però essere ripreso di recente, il che è un segno di speranza. Se uno sviluppatore adeguatamente motivato lo migliorasse per far funzionare rst2pdf con la documentazione del kernel, il mondo gli sarebbe eternamente grato.
Scrivere più documentazione¶
Naturalmente, ci sono vaste parti del kernel che sono gravemente prive di documentazione. Se avete la conoscenza per documentare uno specifico sottosistema del kernel e il desiderio di farlo, non esitate a scrivere e inviare il lavoro al kernel. Un numero incalcolabile di sviluppatori e utenti del kernel vi ringrazierà.