1.. SPDX-License-Identifier: GPL-2.0 2 3.. include:: ../disclaimer-ita.rst 4 5Come contribuire al miglioramento della documentazione del kernel 6================================================================= 7 8La documentazione è una parte importante di ogni progetto di sviluppo 9software. Una buona documentazione aiuta ad attirare nuovi sviluppatori e 10permette a quelli già presenti di lavorare in modo più efficace. Senza una 11documentazione di qualità, si spreca molto tempo nel decifrare il codice a 12ritroso e si commettono errori altrimenti evitabili. 13 14Sfortunatamente, al momento la documentazione del kernel è ben lontana da 15quello che dovrebbe essere per sostenere un progetto di queste dimensioni e 16importanza. 17 18Questa guida è per chi vuole contribuire a migliorare questa situazione. I 19miglioramenti alla documentazione del kernel possono essere fatti da 20sviluppatori con diversi livelli di esperienza; sono un modo relativamente 21semplice per imparare il processo di sviluppo del kernel in generale e 22trovare il proprio posto nella comunità. Quello che segue è, per la maggior 23parte, l'elenco dei compiti che il manutentore della documentazione ritiene 24più urgenti. 25 26Le cose da fare nella documentazione 27------------------------------------ 28 29C'è un elenco infinito di compiti da svolgere per portare la nostra 30documentazione al livello in cui dovrebbe essere. Questo elenco contiene 31alcuni punti importanti, ma è lungi dall'essere esaustivo; se trovate un 32modo diverso per migliorare la documentazione, non esitate! 33 34Correzione degli avvisi 35~~~~~~~~~~~~~~~~~~~~~~~ 36 37Al momento, la generazione della documentazione produce un numero 38incredibile di avvisi. Quando ce ne sono così tanti, è come se non ce ne 39fosse nessuno: le persone li ignorano e non si accorgeranno mai quando il 40loro lavoro ne aggiunge di nuovi. Per questo motivo, eliminare gli avvisi è 41uno dei compiti a più alta priorità nell'elenco delle cose da fare per la 42documentazione. Il compito in sé è ragionevolmente semplice, ma va 43affrontato nel modo giusto per avere successo. 44 45Gli avvisi emessi da un compilatore per il codice C possono spesso essere 46scartati come falsi positivi, portando a patch il cui unico scopo è zittire 47il compilatore. Gli avvisi generati dalla documentazione, invece, indicano 48quasi sempre un problema reale; farli sparire richiede di comprendere il 49problema e correggerlo alla radice. Per questo motivo, le patch che 50correggono avvisi nella documentazione non dovrebbero limitarsi a dire "fix 51a warning" nel titolo del changelog; dovrebbero invece indicare il problema 52reale che è stato corretto. 53 54Un altro punto importante è che gli avvisi nella documentazione sono spesso 55generati da problemi nei commenti kerneldoc all'interno del codice C. Anche se 56il manutentore della documentazione apprezza l'essere messo in copia sulle 57correzioni di questo tipo, in realtà spesso rivolgersi al sottosistema di 58documentazione non è il modo migliore di apportare queste modifiche; queste 59dovrebbero invece essere inviate al manutentore del sottosistema in questione. 60 61Per esempio, in una generazione della documentazione ho preso, quasi a 62caso, un paio di avvisi:: 63 64 ./drivers/devfreq/devfreq.c:1818: warning: bad line: 65 - Resource-managed devfreq_register_notifier() 66 ./drivers/devfreq/devfreq.c:1854: warning: bad line: 67 - Resource-managed devfreq_unregister_notifier() 68 69(Le righe sono state divise per essere più leggibili). 70 71Una rapida occhiata al file sorgente indicato sopra ha rivelato un paio di 72commenti kerneldoc con questo aspetto:: 73 74 /** 75 * devm_devfreq_register_notifier() 76 - Resource-managed devfreq_register_notifier() 77 * @dev: The devfreq user device. (parent of devfreq) 78 * @devfreq: The devfreq object. 79 * @nb: The notifier block to be unregistered. 80 * @list: DEVFREQ_TRANSITION_NOTIFIER. 81 */ 82 83Il problema è l'asterisco mancante, che confonde l'idea semplicistica che il 84sistema di generazione abbia idea di come debba essere fatto un blocco di 85commento C. Questo problema era presente fin da quando quel commento venne 86aggiunto nel 2016, quindi da diversi anni. Correggerlo è stata solo questione di 87aggiungere gli asterischi mancanti. Una rapida occhiata alla cronologia di quel 88file ha mostrato quale fosse il formato usuale per la riga dell'oggetto, e 89``scripts/get_maintainer.pl`` mi ha detto chi dovesse riceverla (basta passare 90il percorso delle vostre patch come argomento a scripts/get_maintainer.pl). La 91patch risultante era questa:: 92 93 [PATCH] PM / devfreq: Fix two malformed kerneldoc comments 94 95 Two kerneldoc comments in devfreq.c fail to adhere to the required format, 96 resulting in these doc-build warnings: 97 98 ./drivers/devfreq/devfreq.c:1818: warning: bad line: 99 - Resource-managed devfreq_register_notifier() 100 ./drivers/devfreq/devfreq.c:1854: warning: bad line: 101 - Resource-managed devfreq_unregister_notifier() 102 103 Add a couple of missing asterisks and make kerneldoc a little happier. 104 105 Signed-off-by: Jonathan Corbet <corbet@lwn.net> 106 --- 107 drivers/devfreq/devfreq.c | 4 ++-- 108 1 file changed, 2 insertions(+), 2 deletions(-) 109 110 diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c 111 index 57f6944d65a6..00c9b80b3d33 100644 112 --- a/drivers/devfreq/devfreq.c 113 +++ b/drivers/devfreq/devfreq.c 114 @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) 115 116 /** 117 * devm_devfreq_register_notifier() 118 - - Resource-managed devfreq_register_notifier() 119 + * - Resource-managed devfreq_register_notifier() 120 * @dev: The devfreq user device. (parent of devfreq) 121 * @devfreq: The devfreq object. 122 * @nb: The notifier block to be unregistered. 123 @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); 124 125 /** 126 * devm_devfreq_unregister_notifier() 127 - - Resource-managed devfreq_unregister_notifier() 128 + * - Resource-managed devfreq_unregister_notifier() 129 * @dev: The devfreq user device. (parent of devfreq) 130 * @devfreq: The devfreq object. 131 * @nb: The notifier block to be unregistered. 132 -- 133 2.24.1 134 135L'intero procedimento ha richiesto solo pochi minuti. Naturalmente, ho poi 136scoperto che qualcun altro l'aveva già corretto in un altro albero, 137mettendo in luce un'altra lezione: controllate sempre linux-next per 138vedere se un problema è già stato risolto prima di mettervici sopra. 139 140Altre correzioni richiederanno più tempo, specialmente quelle relative ai 141campi di una struttura o ai parametri di una funzione privi di 142documentazione. In questi casi, è necessario capire quale sia il ruolo di 143questi campi o parametri e descriverli correttamente. Nel complesso, questo 144compito diventa un po' tedioso a volte, ma è molto importante. Se riusciamo 145davvero ad eliminare gli avvisi dalla generazione della documentazione, 146allora potremo iniziare a pretendere che gli sviluppatori evitino di 147aggiungerne di nuovi. 148 149Oltre ai normali avvisi durante la generazione della documentazione, potete 150ottenerne di più eseguendo ``make refcheckdocs`` per trovare riferimenti a file 151di documentazione inesistenti. 152 153Commenti kerneldoc dimenticati 154~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 155 156Gli sviluppatori sono incoraggiati a scrivere commenti kerneldoc per il 157loro codice, ma molti di questi commenti non vengono mai inclusi nella 158generazione della documentazione. Questo rende tale informazione più 159difficile da trovare e, per esempio, impedisce a Sphinx di generare 160collegamenti verso quella documentazione. Aggiungere le direttive 161``kernel-doc`` alla documentazione per includere quei commenti può aiutare 162la comunità a ottenere il pieno valore del lavoro speso per crearli. 163 164Lo strumento ``tools/docs/find-unused-docs.sh`` può essere usato per 165trovare questi commenti dimenticati. 166 167Da notare che il valore maggiore deriva dall'includere la documentazione 168per le funzioni e le strutture dati esportate. Molti sottosistemi hanno 169anche commenti kerneldoc per uso interno; questi non dovrebbero essere 170inclusi nella generazione della documentazione a meno che non vengano 171posti in un documento specificamente rivolto agli sviluppatori che 172lavorano all'interno del sottosistema in questione. 173 174 175Correzione dei refusi 176~~~~~~~~~~~~~~~~~~~~~ 177 178Correggere errori di battitura o di formattazione nella documentazione è 179un modo rapido per imparare come creare e inviare patch, ed è un servizio 180utile. Sono sempre disposto ad accettare questo tipo di patch. Detto 181questo, una volta che ne avete corretti alcuni, considerate di passare a 182compiti più avanzati, lasciando qualche refuso per il prossimo principiante 183che vorrà occuparsene. 184 185Da notare che alcune cose *non* sono refusi e non dovrebbero essere 186"corrette": 187 188 - Sia la grafia americana che quella britannica dell'inglese sono 189 ammesse nella documentazione del kernel. Non c'è bisogno di sostituire 190 l'una con l'altra. 191 192 - La questione se un punto debba essere seguito da uno o due spazi non 193 va dibattuta nel contesto della documentazione del kernel. Anche 194 altri argomenti di legittimo disaccordo, come la "virgola di Oxford", 195 non sono pertinenti qui. 196 197Come per qualsiasi patch a qualsiasi progetto, considerate se la vostra 198modifica sta davvero migliorando le cose. 199 200Documentazione datata 201~~~~~~~~~~~~~~~~~~~~~ 202 203Parte della documentazione del kernel è attuale, mantenuta e utile. 204Un'altra parte... non lo è. Documentazione impolverata, vecchia e 205imprecisa può fuorviare i lettori e gettare discredito sulla nostra 206documentazione nel suo complesso. Qualsiasi cosa si possa fare per 207affrontare questi problemi è più che benvenuta. 208 209Ogni volta che lavorate su un documento, considerate se è attuale, se ha 210bisogno di essere aggiornato, o se forse dovrebbe essere rimosso del 211tutto. Ci sono alcuni segnali d'allarme a cui potete prestare attenzione: 212 213 - Riferimenti a kernel della serie 2.x 214 - Rimandi a repositori su SourceForge 215 - Nella cronologia, negli ultimi anni, solo correzioni di refusi 216 - Discussioni su modi di lavorare precedenti a Git 217 218La cosa migliore da fare, ovviamente, sarebbe portare la documentazione a 219essere attuale, aggiungendo qualsiasi informazione necessaria. Un lavoro 220simile spesso richiede la collaborazione di sviluppatori che conoscono bene 221il sottosistema in questione. Gli sviluppatori, quando viene chiesto loro 222gentilmente, e quando le loro risposte vengono ascoltate e messe in 223pratica, sono spesso più che disposti a collaborare con chi lavora per 224migliorare la documentazione. 225 226Alcuni documenti sono senza speranza; a volte troviamo documenti che fanno 227riferimento a codice rimosso dal kernel molto tempo fa, per esempio. C'è 228una sorprendente resistenza a rimuovere la documentazione obsoleta, ma 229dovremmo farlo comunque. Il materiale superfluo nella nostra documentazione 230non è d'aiuto a nessuno. 231 232Nei casi in cui, forse, ci sono informazioni utili in un documento 233gravemente datato, e non siete in grado di aggiornarlo, la cosa migliore 234da fare potrebbe essere aggiungere un avviso all'inizio. Si raccomanda il 235seguente testo:: 236 237 .. warning :: 238 This document is outdated and in need of attention. Please use 239 this information with caution, and please consider sending patches 240 to update it. 241 242In questo modo, almeno i nostri pazientissimi lettori sono stati avvisati 243che il documento potrebbe portarli fuori strada. 244 245Coerenza della documentazione 246~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 247 248I veterani di qui ricorderanno i libri su Linux che comparvero sugli 249scaffali negli anni '90. Erano semplicemente raccolte di file di 250documentazione racimolati da varie fonti in rete. I libri sono (per lo 251più) migliorati da allora, ma la documentazione del kernel è ancora per lo 252più costruita su quel modello. Sono migliaia di file, quasi ognuno dei 253quali è stato scritto in isolamento da tutti gli altri. Non abbiamo un 254corpo coerente di documentazione del kernel; abbiamo migliaia di documenti 255individuali. 256 257Abbiamo cercato di migliorare la situazione creando un insieme di "libri" 258che raggruppano la documentazione per specifici lettori. Questi 259includono: 260 261 - Documentation/admin-guide/index.rst 262 - Documentation/core-api/index.rst 263 - Documentation/driver-api/index.rst 264 - Documentation/userspace-api/index.rst 265 266Così come questo libro sulla documentazione stessa. 267 268Spostare i documenti nei libri appropriati è un compito importante e deve 269continuare. Ci sono, tuttavia, un paio di sfide associate a questo lavoro. 270Spostare i file della documentazione, nel breve termine, infastidisce chi vi 271lavora; comprensibilmente, non sono entusiasti di questi cambiamenti. Di solito 272li si può convincere a spostarli una volta; tuttavia, non vogliamo continuare a 273spostarli in giro. 274 275Anche quando tutti i documenti sono al posto giusto, però, siamo solo 276riusciti a trasformare un grande cumulo in un gruppo di cumuli più 277piccoli. Il lavoro di cercare di tessere insieme tutti quei documenti in 278un unico insieme non è ancora iniziato. Se avete idee brillanti su come 279potremmo procedere su questo fronte, saremmo più che felici di sentirle. 280 281Miglioramenti al foglio di stile 282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 283 284Con l'adozione di Sphinx abbiamo un output HTML dall'aspetto molto più gradevole 285di quanto avessimo un tempo. Ma è ancora migliorabile; Donald Knuth e Edward 286Tufte non ne sarebbero impressionati. Questo richiede di modificare i nostri 287fogli di stile per creare un output tipograficamente più solido, accessibile e 288leggibile. 289 290Attenzione: se vi assumete questo compito, vi state addentrando nel 291classico territorio del "bikeshed". Aspettatevi molte opinioni e 292discussioni anche per cambiamenti relativamente ovvi. Questa è, ahimè, la 293natura del mondo in cui viviamo. 294 295Generazione di PDF senza LaTeX 296~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 297 298Questo è un compito decisamente non banale per qualcuno con molto tempo a 299disposizione e competenze in Python. La catena di strumenti di Sphinx è 300relativamente piccola e ben contenuta; è facile da aggiungere a un sistema 301di sviluppo. Ma generare output in PDF o EPUB richiede l'installazione di 302LaTeX, che non è affatto piccolo o ben contenuto. Sarebbe una bella cosa 303da eliminare. 304 305La speranza originale era di usare lo strumento rst2pdf (https://rst2pdf.org/) 306per la generazione dei PDF, ma si è scoperto che non era all'altezza del 307compito. Il lavoro di sviluppo su rst2pdf sembra però essere ripreso di recente, 308il che è un segno di speranza. Se uno sviluppatore adeguatamente motivato lo 309migliorasse per far funzionare rst2pdf con la documentazione del kernel, il 310mondo gli sarebbe eternamente grato. 311 312Scrivere più documentazione 313~~~~~~~~~~~~~~~~~~~~~~~~~~~ 314 315Naturalmente, ci sono vaste parti del kernel che sono gravemente prive di 316documentazione. Se avete la conoscenza per documentare uno specifico 317sottosistema del kernel e il desiderio di farlo, non esitate a scrivere e 318inviare il lavoro al kernel. Un numero incalcolabile di 319sviluppatori e utenti del kernel vi ringrazierà. 320