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