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