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 373Marcatori e riferimenti 374----------------------- 375 376All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti 377*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti 378del `dominio Sphinx per il C`_. 379 380.. attention:: Questi sono riconosciuti **solo** all'interno di commenti 381 kernel-doc, e **non** all'interno di documenti reStructuredText. 382 383``funcname()`` 384 Riferimento ad una funzione. 385 386``@parameter`` 387 Nome di un parametro di una funzione (nessun riferimento, solo formattazione). 388 389``%CONST`` 390 Il nome di una costante (nessun riferimento, solo formattazione) 391 392````literal```` 393 Un blocco di testo che deve essere riportato così com'è. La rappresentazione 394 finale utilizzerà caratteri a ``spaziatura fissa``. 395 396 Questo è utile se dovete utilizzare caratteri speciali che altrimenti 397 potrebbero assumere un significato diverso in kernel-doc o in reStructuredText 398 399 Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph`` 400 all'interno della descrizione di una funzione. 401 402``$ENVVAR`` 403 Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione). 404 405``&struct name`` 406 Riferimento ad una struttura. 407 408``&enum name`` 409 Riferimento ad un'enumerazione. 410 411``&typedef name`` 412 Riferimento ad un tipo di dato. 413 414``&struct_name->member`` or ``&struct_name.member`` 415 Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà 416 la struttura o l'unione, non il memembro. 417 418``&name`` 419 Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento 420 completo come descritto sopra. Questo è dedicato ai commenti obsoleti. 421 422Riferimenti usando reStructuredText 423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 424 425Nei documenti reStructuredText non serve alcuna sintassi speciale per 426fare riferimento a funzioni e tipi definiti nei commenti 427kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``, 428e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un 429tipo. Per esempio:: 430 431 See foo() 432 See struct foo. 433 See union bar. 434 See enum baz. 435 See typedef meh. 436 437Tuttavia, la personalizzazione dei collegamenti è possibile solo con 438la seguente sintassi:: 439 440 See :c:func:`my custom link text for function foo <foo>`. 441 See :c:type:`my custom link text for struct bar <bar>`. 442 443 444Commenti per una documentazione generale 445---------------------------------------- 446 447Al fine d'avere il codice ed i commenti nello stesso file, potete includere 448dei blocchi di documentazione kernel-doc con un formato libero invece 449che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi 450di dato. Per esempio, questo tipo di commento potrebbe essere usato per la 451spiegazione delle operazioni di un driver o di una libreria 452 453Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato 454un titolo. 455 456Generalmente il formato di un commento generico o di visione d'insieme è 457il seguente:: 458 459 /** 460 * DOC: Theory of Operation 461 * 462 * The whizbang foobar is a dilly of a gizmo. It can do whatever you 463 * want it to do, at any time. It reads your mind. Here's how it works. 464 * 465 * foo bar splat 466 * 467 * The only drawback to this gizmo is that is can sometimes damage 468 * hardware, software, or its subject(s). 469 */ 470 471Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file 472sorgente, ma anche come identificatore per l'estrazione di questi commenti di 473documentazione. Quindi, il titolo dev'essere unico all'interno del file. 474 475======================================= 476Includere i commenti di tipo kernel-doc 477======================================= 478 479I commenti di documentazione possono essere inclusi in un qualsiasi documento 480di tipo reStructuredText mediante l'apposita direttiva nell'estensione 481kernel-doc per Sphinx. 482 483Le direttive kernel-doc sono nel formato:: 484 485 .. kernel-doc:: source 486 :option: 487 488Il campo *source* è il percorso ad un file sorgente, relativo alla cartella 489principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni: 490 491export: *[source-pattern ...]* 492 Include la documentazione per tutte le funzioni presenti nel file sorgente 493 (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o 494 ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* 495 specificato. 496 497 Il campo *source-patter* è utile quando i commenti kernel-doc sono stati 498 scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e 499 ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni. 500 501 Esempi:: 502 503 .. kernel-doc:: lib/bitmap.c 504 :export: 505 506 .. kernel-doc:: include/net/mac80211.h 507 :export: net/mac80211/*.c 508 509internal: *[source-pattern ...]* 510 Include la documentazione per tutte le funzioni ed i tipi presenti nel file 511 sorgente (*source*) che **non** sono stati esportati utilizzando 512 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi 513 altro *source-pattern* specificato. 514 515 Esempio:: 516 517 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 518 :internal: 519 520identifiers: *[ function/type ...]* 521 Include la documentazione per ogni *function* e *type* in *source*. 522 Se non vengono esplicitamente specificate le funzioni da includere, allora 523 verranno incluse tutte quelle disponibili in *source*. 524 525 Esempi:: 526 527 .. kernel-doc:: lib/bitmap.c 528 :identifiers: bitmap_parselist bitmap_parselist_user 529 530 .. kernel-doc:: lib/idr.c 531 :identifiers: 532 533functions: *[ function ...]* 534 Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'. 535 536doc: *title* 537 Include la documentazione del paragrafo ``DOC:`` identificato dal titolo 538 (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono 539 permessi; non virgolettate *title*. Il campo *title* è utilizzato per 540 identificare un paragrafo e per questo non viene incluso nella documentazione 541 finale. Verificate d'avere l'intestazione appropriata nei documenti 542 reStructuredText. 543 544 Esempio:: 545 546 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 547 :doc: High Definition Audio over HDMI and Display Port 548 549Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di 550documentazione presenti nel file sorgente (*source*). 551 552L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare 553in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato 554lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione 555dai file sorgenti. 556 557Come utilizzare kernel-doc per generare pagine man 558-------------------------------------------------- 559 560Se volete utilizzare kernel-doc solo per generare delle pagine man, potete 561farlo direttamente dai sorgenti del kernel:: 562 563 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man 564