kernel-doc.rst (19581B)
1.. include:: ../disclaimer-ita.rst 2 3.. note:: Per leggere la documentazione originale in inglese: 4 :ref:`Documentation/doc-guide/index.rst <doc_guide>` 5 6.. _it_kernel_doc: 7 8Scrivere i commenti in kernel-doc 9================================= 10 11Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione 12strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni, 13tipi di dati, e l'architettura del codice. 14 15.. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma 16 in realtà è molto differente per ragioni storiche. I sorgenti del kernel 17 contengono decine di migliaia di commenti kernel-doc. Siete pregati 18 d'attenervi allo stile qui descritto. 19 20La struttura kernel-doc è estratta a partire dai commenti; da questi viene 21generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le 22funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni 23vengono filtrare per cercare i riferimenti ed i marcatori. 24 25Vedere di seguito per maggiori dettagli. 26 27.. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html 28 29Tutte le funzioni esportate verso i moduli esterni utilizzando 30``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento 31kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni 32e le strutture dati nei file d'intestazione dovrebbero avere dei commenti 33kernel-doc. 34 35È considerata una buona pratica quella di fornire una documentazione formattata 36secondo kernel-doc per le funzioni che sono visibili da altri file del kernel 37(ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo, 38inoltre, di fornire una documentazione kernel-doc anche per procedure private 39(ovvero, dichiarate "static") al fine di fornire una struttura più coerente 40dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a 41discrezione dal manutentore (MAINTAINER) del file sorgente. 42 43 44 45Sicuramente la documentazione formattata con kernel-doc è necessaria per 46le funzioni che sono esportate verso i moduli esterni utilizzando 47``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``. 48 49Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc 50per le funzioni che sono visibili da altri file del kernel (ovvero, che non 51siano dichiarate utilizzando "static") 52 53Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc 54anche per procedure private (ovvero, dichiarate "static") al fine di fornire 55una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità 56più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente. 57 58Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse 59documentate utilizzando commenti formattati con kernel-doc. 60 61Come formattare i commenti kernel-doc 62------------------------------------- 63 64I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma 65``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto 66del commento è formattato come un normale commento multilinea, ovvero 67con un asterisco all'inizio d'ogni riga e che si conclude con ``*/`` 68su una riga separata. 69 70I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati 71appena sopra la funzione od il tipo che descrivono. Questo allo scopo di 72aumentare la probabilità che chi cambia il codice si ricordi di aggiornare 73anche la documentazione. I commenti kernel-doc di tipo più generale possono 74essere posizionati ovunque nel file. 75 76Al fine di verificare che i commenti siano formattati correttamente, potete 77eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza 78che questo produca alcuna documentazione. Per esempio:: 79 80 scripts/kernel-doc -v -none drivers/foo/bar.c 81 82Il formato della documentazione è verificato della procedura di generazione 83del kernel quando viene richiesto di effettuare dei controlli extra con GCC:: 84 85 make W=n 86 87Documentare le funzioni 88------------------------ 89 90Generalmente il formato di un commento kernel-doc per funzioni e 91macro simil-funzioni è il seguente:: 92 93 /** 94 * function_name() - Brief description of function. 95 * @arg1: Describe the first argument. 96 * @arg2: Describe the second argument. 97 * One can provide multiple line descriptions 98 * for arguments. 99 * 100 * A longer description, with more discussion of the function function_name() 101 * that might be useful to those using or modifying it. Begins with an 102 * empty comment line, and may include additional embedded empty 103 * comment lines. 104 * 105 * The longer description may have multiple paragraphs. 106 * 107 * Context: Describes whether the function can sleep, what locks it takes, 108 * releases, or expects to be held. It can extend over multiple 109 * lines. 110 * Return: Describe the return value of function_name. 111 * 112 * The return value description can also have multiple paragraphs, and should 113 * be placed at the end of the comment block. 114 */ 115 116La descrizione introduttiva (*brief description*) che segue il nome della 117funzione può continuare su righe successive e termina con la descrizione di 118un argomento, una linea di commento vuota, oppure la fine del commento. 119 120Parametri delle funzioni 121~~~~~~~~~~~~~~~~~~~~~~~~ 122 123Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito 124dopo la descrizione introduttiva. Non lasciare righe vuote né fra la 125descrizione introduttiva e quella degli argomenti, né fra gli argomenti. 126 127Ogni ``@argument:`` può estendersi su più righe. 128 129.. note:: 130 131 Se la descrizione di ``@argument:`` si estende su più righe, 132 la continuazione dovrebbe iniziare alla stessa colonna della riga 133 precedente:: 134 135 * @argument: some long description 136 * that continues on next lines 137 138 or:: 139 140 * @argument: 141 * some long description 142 * that continues on next lines 143 144Se una funzione ha un numero variabile di argomento, la sua descrizione 145dovrebbe essere scritta con la notazione kernel-doc:: 146 147 * @...: description 148 149Contesto delle funzioni 150~~~~~~~~~~~~~~~~~~~~~~~ 151 152Il contesto in cui le funzioni vengono chiamate viene descritto in una 153sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità 154che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto 155d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che 156vengano presi dal chiamante. 157 158Esempi:: 159 160 * Context: Any context. 161 * Context: Any context. Takes and releases the RCU lock. 162 * Context: Any context. Expects <lock> to be held by caller. 163 * Context: Process context. May sleep if @gfp flags permit. 164 * Context: Process context. Takes and releases <mutex>. 165 * Context: Softirq or process context. Takes and releases <lock>, BH-safe. 166 * Context: Interrupt context. 167 168Valore di ritorno 169~~~~~~~~~~~~~~~~~ 170 171Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome 172``Return``. 173 174.. note:: 175 176 #) La descrizione multiriga non riconosce il termine d'una riga, per cui 177 se provate a formattare bene il vostro testo come nel seguente esempio:: 178 179 * Return: 180 * 0 - OK 181 * -EINVAL - invalid argument 182 * -ENOMEM - out of memory 183 184 le righe verranno unite e il risultato sarà:: 185 186 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory 187 188 Quindi, se volete che le righe vengano effettivamente generate, dovete 189 utilizzare una lista ReST, ad esempio:: 190 191 * Return: 192 * * 0 - OK to runtime suspend the device 193 * * -EBUSY - Device should not be runtime suspended 194 195 #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai 196 due punti, allora ognuna di queste frasi verrà considerata come il nome 197 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati. 198 199Documentare strutture, unioni ed enumerazioni 200--------------------------------------------- 201 202Generalmente il formato di un commento kernel-doc per struct, union ed enum è:: 203 204 /** 205 * struct struct_name - Brief description. 206 * @member1: Description of member1. 207 * @member2: Description of member2. 208 * One can provide multiple line descriptions 209 * for members. 210 * 211 * Description of the structure. 212 */ 213 214Nell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum`` 215per descrivere unioni ed enumerati. ``member`` viene usato per indicare i 216membri di strutture ed unioni, ma anche i valori di un tipo enumerato. 217 218La descrizione introduttiva (*brief description*) che segue il nome della 219funzione può continuare su righe successive e termina con la descrizione di 220un argomento, una linea di commento vuota, oppure la fine del commento. 221 222Membri 223~~~~~~ 224 225I membri di strutture, unioni ed enumerati devo essere documentati come i 226parametri delle funzioni; seguono la descrizione introduttiva e possono 227estendersi su più righe. 228 229All'interno d'una struttura o d'un unione, potete utilizzare le etichette 230``private:`` e ``public:``. I campi che sono nell'area ``private:`` non 231verranno inclusi nella documentazione finale. 232 233Le etichette ``private:`` e ``public:`` devono essere messe subito dopo 234il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti 235fra ``:`` e il marcatore di fine commento ``*/``. 236 237Esempio:: 238 239 /** 240 * struct my_struct - short description 241 * @a: first member 242 * @b: second member 243 * @d: fourth member 244 * 245 * Longer description 246 */ 247 struct my_struct { 248 int a; 249 int b; 250 /* private: internal use only */ 251 int c; 252 /* public: the next one is public */ 253 int d; 254 }; 255 256Strutture ed unioni annidate 257~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 258 259È possibile documentare strutture ed unioni annidate, ad esempio:: 260 261 /** 262 * struct nested_foobar - a struct with nested unions and structs 263 * @memb1: first member of anonymous union/anonymous struct 264 * @memb2: second member of anonymous union/anonymous struct 265 * @memb3: third member of anonymous union/anonymous struct 266 * @memb4: fourth member of anonymous union/anonymous struct 267 * @bar: non-anonymous union 268 * @bar.st1: struct st1 inside @bar 269 * @bar.st2: struct st2 inside @bar 270 * @bar.st1.memb1: first member of struct st1 on union bar 271 * @bar.st1.memb2: second member of struct st1 on union bar 272 * @bar.st2.memb1: first member of struct st2 on union bar 273 * @bar.st2.memb2: second member of struct st2 on union bar 274 */ 275 struct nested_foobar { 276 /* Anonymous union/struct*/ 277 union { 278 struct { 279 int memb1; 280 int memb2; 281 } 282 struct { 283 void *memb3; 284 int memb4; 285 } 286 } 287 union { 288 struct { 289 int memb1; 290 int memb2; 291 } st1; 292 struct { 293 void *memb1; 294 int memb2; 295 } st2; 296 } bar; 297 }; 298 299.. note:: 300 301 #) Quando documentate una struttura od unione annidata, ad esempio 302 di nome ``foo``, il suo campo ``bar`` dev'essere documentato 303 usando ``@foo.bar:`` 304 #) Quando la struttura od unione annidata è anonima, il suo campo 305 ``bar`` dev'essere documentato usando ``@bar:`` 306 307Commenti in linea per la documentazione dei membri 308~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 309 310I membri d'una struttura possono essere documentati in linea all'interno 311della definizione stessa. Ci sono due stili: una singola riga di commento 312che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come 313qualsiasi altro commento kernel-doc:: 314 315 /** 316 * struct foo - Brief description. 317 * @foo: The Foo member. 318 */ 319 struct foo { 320 int foo; 321 /** 322 * @bar: The Bar member. 323 */ 324 int bar; 325 /** 326 * @baz: The Baz member. 327 * 328 * Here, the member description may contain several paragraphs. 329 */ 330 int baz; 331 union { 332 /** @foobar: Single line description. */ 333 int foobar; 334 }; 335 /** @bar2: Description for struct @bar2 inside @foo */ 336 struct { 337 /** 338 * @bar2.barbar: Description for @barbar inside @foo.bar2 339 */ 340 int barbar; 341 } bar2; 342 }; 343 344 345Documentazione dei tipi di dato 346------------------------------- 347Generalmente il formato di un commento kernel-doc per typedef è 348il seguente:: 349 350 /** 351 * typedef type_name - Brief description. 352 * 353 * Description of the type. 354 */ 355 356Anche i tipi di dato per prototipi di funzione possono essere documentati:: 357 358 /** 359 * typedef type_name - Brief description. 360 * @arg1: description of arg1 361 * @arg2: description of arg2 362 * 363 * Description of the type. 364 * 365 * Context: Locking context. 366 * Return: Meaning of the return value. 367 */ 368 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); 369 370Marcatori e riferimenti 371----------------------- 372 373All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti 374*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti 375del `dominio Sphinx per il C`_. 376 377.. attention:: Questi sono riconosciuti **solo** all'interno di commenti 378 kernel-doc, e **non** all'interno di documenti reStructuredText. 379 380``funcname()`` 381 Riferimento ad una funzione. 382 383``@parameter`` 384 Nome di un parametro di una funzione (nessun riferimento, solo formattazione). 385 386``%CONST`` 387 Il nome di una costante (nessun riferimento, solo formattazione) 388 389````literal```` 390 Un blocco di testo che deve essere riportato così com'è. La rappresentazione 391 finale utilizzerà caratteri a ``spaziatura fissa``. 392 393 Questo è utile se dovete utilizzare caratteri speciali che altrimenti 394 potrebbero assumere un significato diverso in kernel-doc o in reStructuredText 395 396 Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph`` 397 all'interno della descrizione di una funzione. 398 399``$ENVVAR`` 400 Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione). 401 402``&struct name`` 403 Riferimento ad una struttura. 404 405``&enum name`` 406 Riferimento ad un'enumerazione. 407 408``&typedef name`` 409 Riferimento ad un tipo di dato. 410 411``&struct_name->member`` or ``&struct_name.member`` 412 Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà 413 la struttura o l'unione, non il memembro. 414 415``&name`` 416 Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento 417 completo come descritto sopra. Questo è dedicato ai commenti obsoleti. 418 419Riferimenti usando reStructuredText 420~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 421 422Nei documenti reStructuredText non serve alcuna sintassi speciale per 423fare riferimento a funzioni e tipi definiti nei commenti 424kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``, 425e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un 426tipo. Per esempio:: 427 428 See foo() 429 See struct foo. 430 See union bar. 431 See enum baz. 432 See typedef meh. 433 434Tuttavia, la personalizzazione dei collegamenti è possibile solo con 435la seguente sintassi:: 436 437 See :c:func:`my custom link text for function foo <foo>`. 438 See :c:type:`my custom link text for struct bar <bar>`. 439 440 441Commenti per una documentazione generale 442---------------------------------------- 443 444Al fine d'avere il codice ed i commenti nello stesso file, potete includere 445dei blocchi di documentazione kernel-doc con un formato libero invece 446che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi 447di dato. Per esempio, questo tipo di commento potrebbe essere usato per la 448spiegazione delle operazioni di un driver o di una libreria 449 450Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato 451un titolo. 452 453Generalmente il formato di un commento generico o di visione d'insieme è 454il seguente:: 455 456 /** 457 * DOC: Theory of Operation 458 * 459 * The whizbang foobar is a dilly of a gizmo. It can do whatever you 460 * want it to do, at any time. It reads your mind. Here's how it works. 461 * 462 * foo bar splat 463 * 464 * The only drawback to this gizmo is that is can sometimes damage 465 * hardware, software, or its subject(s). 466 */ 467 468Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file 469sorgente, ma anche come identificatore per l'estrazione di questi commenti di 470documentazione. Quindi, il titolo dev'essere unico all'interno del file. 471 472Includere i commenti di tipo kernel-doc 473======================================= 474 475I commenti di documentazione possono essere inclusi in un qualsiasi documento 476di tipo reStructuredText mediante l'apposita direttiva nell'estensione 477kernel-doc per Sphinx. 478 479Le direttive kernel-doc sono nel formato:: 480 481 .. kernel-doc:: source 482 :option: 483 484Il campo *source* è il percorso ad un file sorgente, relativo alla cartella 485principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni: 486 487export: *[source-pattern ...]* 488 Include la documentazione per tutte le funzioni presenti nel file sorgente 489 (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o 490 ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* 491 specificato. 492 493 Il campo *source-patter* è utile quando i commenti kernel-doc sono stati 494 scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e 495 ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni. 496 497 Esempi:: 498 499 .. kernel-doc:: lib/bitmap.c 500 :export: 501 502 .. kernel-doc:: include/net/mac80211.h 503 :export: net/mac80211/*.c 504 505internal: *[source-pattern ...]* 506 Include la documentazione per tutte le funzioni ed i tipi presenti nel file 507 sorgente (*source*) che **non** sono stati esportati utilizzando 508 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi 509 altro *source-pattern* specificato. 510 511 Esempio:: 512 513 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 514 :internal: 515 516identifiers: *[ function/type ...]* 517 Include la documentazione per ogni *function* e *type* in *source*. 518 Se non vengono esplicitamente specificate le funzioni da includere, allora 519 verranno incluse tutte quelle disponibili in *source*. 520 521 Esempi:: 522 523 .. kernel-doc:: lib/bitmap.c 524 :identifiers: bitmap_parselist bitmap_parselist_user 525 526 .. kernel-doc:: lib/idr.c 527 :identifiers: 528 529functions: *[ function ...]* 530 Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'. 531 532doc: *title* 533 Include la documentazione del paragrafo ``DOC:`` identificato dal titolo 534 (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono 535 permessi; non virgolettate *title*. Il campo *title* è utilizzato per 536 identificare un paragrafo e per questo non viene incluso nella documentazione 537 finale. Verificate d'avere l'intestazione appropriata nei documenti 538 reStructuredText. 539 540 Esempio:: 541 542 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 543 :doc: High Definition Audio over HDMI and Display Port 544 545Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di 546documentazione presenti nel file sorgente (*source*). 547 548L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare 549in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato 550lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione 551dai file sorgenti. 552 553Come utilizzare kernel-doc per generare pagine man 554-------------------------------------------------- 555 556Se volete utilizzare kernel-doc solo per generare delle pagine man, potete 557farlo direttamente dai sorgenti del kernel:: 558 559 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man