Documentation/translations/it_IT/doc-guide/kernel-doc.rst

   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 =================================
  11 Scrivere i commenti in kernel-doc
  12 =================================
  13
  14 Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione
  15 strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni,
  16 tipi 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
  23 La struttura kernel-doc è estratta a partire dai commenti; da questi viene
  24 generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le
  25 funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni
  26 vengono filtrare per cercare i riferimenti ed i marcatori.
  27
  28 Vedere di seguito per maggiori dettagli.
  29
  30 .. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
  31
  32 Tutte le funzioni esportate verso i moduli esterni utilizzando
  33 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento
  34 kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni
  35 e le strutture dati nei file d'intestazione dovrebbero avere dei commenti
  36 kernel-doc.
  37
  38 È considerata una buona pratica quella di fornire una documentazione formattata
  39 secondo kernel-doc per le funzioni che sono visibili da altri file del kernel
  40 (ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo,
  41 inoltre, di fornire una documentazione kernel-doc anche per procedure private
  42 (ovvero, dichiarate "static") al fine di fornire una struttura più coerente
  43 dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a
  44 discrezione dal manutentore (MAINTAINER) del file sorgente.
  45
  46
  47
  48 Sicuramente la documentazione formattata con kernel-doc è necessaria per
  49 le funzioni che sono esportate verso i moduli esterni utilizzando
  50 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.
  51
  52 Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
  53 per le funzioni che sono visibili da altri file del kernel (ovvero, che non
  54 siano dichiarate utilizzando "static")
  55
  56 Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
  57 anche per procedure private (ovvero, dichiarate "static") al fine di fornire
  58 una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità
  59 più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.
  60
  61 Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse
  62 documentate utilizzando commenti formattati con kernel-doc.
  63
  64 Come formattare i commenti kernel-doc
  65 -------------------------------------
  66
  67 I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma
  68 ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto
  69 del commento è formattato come un normale commento multilinea, ovvero
  70 con un asterisco all'inizio d'ogni riga e che si conclude con ``*/``
  71 su una riga separata.
  72
  73 I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati
  74 appena sopra la funzione od il tipo che descrivono. Questo allo scopo di
  75 aumentare la probabilità che chi cambia il codice si ricordi di aggiornare
  76 anche la documentazione. I commenti kernel-doc di tipo più generale possono
  77 essere posizionati ovunque nel file.
  78
  79 Al fine di verificare che i commenti siano formattati correttamente, potete
  80 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
  81 che questo produca alcuna documentazione. Per esempio::
  82
  83         scripts/kernel-doc -v -none drivers/foo/bar.c
  84
  85 Il formato della documentazione è verificato della procedura di generazione
  86 del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
  87
  88         make W=n
  89
  90 Documentare le funzioni
  91 ------------------------
  92
  93 Generalmente il formato di un commento kernel-doc per funzioni e
  94 macro 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
 119 La descrizione introduttiva (*brief description*) che segue il nome della
 120 funzione può continuare su righe successive e termina con la descrizione di
 121 un argomento, una linea di commento vuota, oppure la fine del commento.
 122
 123 Parametri delle funzioni
 124 ~~~~~~~~~~~~~~~~~~~~~~~~
 125
 126 Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito
 127 dopo la descrizione introduttiva.  Non lasciare righe vuote né fra la
 128 descrizione introduttiva e quella degli argomenti, né fra gli argomenti.
 129
 130 Ogni ``@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
 147 Se una funzione ha un numero variabile di argomento, la sua descrizione
 148 dovrebbe essere scritta con la notazione kernel-doc::
 149
 150       * @...: description
 151
 152 Contesto delle funzioni
 153 ~~~~~~~~~~~~~~~~~~~~~~~
 154
 155 Il contesto in cui le funzioni vengono chiamate viene descritto in una
 156 sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità
 157 che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto
 158 d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che
 159 vengano presi dal chiamante.
 160
 161 Esempi::
 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
 171 Valore di ritorno
 172 ~~~~~~~~~~~~~~~~~
 173
 174 Il 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
 202 Documentare strutture, unioni ed enumerazioni
 203 ---------------------------------------------
 204
 205 Generalmente 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
 217 Nell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum``
 218 per descrivere unioni ed enumerati. ``member`` viene usato per indicare i
 219 membri di strutture ed unioni, ma anche i valori di un tipo enumerato.
 220
 221 La descrizione introduttiva (*brief description*) che segue il nome della
 222 funzione può continuare su righe successive e termina con la descrizione di
 223 un argomento, una linea di commento vuota, oppure la fine del commento.
 224
 225 Membri
 226 ~~~~~~
 227
 228 I membri di strutture, unioni ed enumerati devo essere documentati come i
 229 parametri delle funzioni; seguono la descrizione introduttiva e possono
 230 estendersi su più righe.
 231
 232 All'interno d'una struttura o d'un unione, potete utilizzare le etichette
 233 ``private:`` e ``public:``. I campi che sono nell'area ``private:`` non
 234 verranno inclusi nella documentazione finale.
 235
 236 Le etichette ``private:`` e ``public:`` devono essere messe subito dopo
 237 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
 238 fra ``:`` e il marcatore di fine commento ``*/``.
 239
 240 Esempio::
 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
 259 Strutture 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
 310 Commenti in linea per la documentazione dei membri
 311 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 312
 313 I membri d'una struttura possono essere documentati in linea all'interno
 314 della definizione stessa. Ci sono due stili: una singola riga di commento
 315 che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come
 316 qualsiasi 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
 348 Documentazione dei tipi di dato
 349 -------------------------------
 350 Generalmente il formato di un commento kernel-doc per typedef è
 351 il seguente::
 352
 353   /**
 354    * typedef type_name - Brief description.
 355    *
 356    * Description of the type.
 357    */
 358
 359 Anche 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
 373 Documentazione di macro simili a oggetti
 374 ----------------------------------------
 375
 376 Le macro simili a oggetti si distinguono dalle macro simili a funzione. Esse si
 377 distinguono in base al fatto che il nome della macro simile a funzione sia
 378 immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
 379 oggetti no.
 380
 381 Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
 382 Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
 383 elenco di parametri.
 384
 385 Il 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
 393 Esempio::
 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
 404 Esempio::
 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
 417 Marcatori e riferimenti
 418 -----------------------
 419
 420 All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
 421 *pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti
 422 del `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
 466 Riferimenti usando reStructuredText
 467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 468
 469 Nei documenti reStructuredText non serve alcuna sintassi speciale per
 470 fare riferimento a funzioni e tipi definiti nei commenti
 471 kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,
 472 e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un
 473 tipo. Per esempio::
 474
 475   See foo()
 476   See struct foo.
 477   See union bar.
 478   See enum baz.
 479   See typedef meh.
 480
 481 Tuttavia, la personalizzazione dei collegamenti è possibile solo con
 482 la 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
 488 Commenti per una documentazione generale
 489 ----------------------------------------
 490
 491 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
 492 dei blocchi di documentazione kernel-doc con un formato libero invece
 493 che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
 494 di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
 495 spiegazione delle operazioni di un driver o di una libreria
 496
 497 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
 498 un titolo.
 499
 500 Generalmente il formato di un commento generico o di visione d'insieme è
 501 il 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
 515 Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file
 516 sorgente, ma anche come identificatore per l'estrazione di questi commenti di
 517 documentazione. Quindi, il titolo dev'essere unico all'interno del file.
 518
 519 =======================================
 520 Includere i commenti di tipo kernel-doc
 521 =======================================
 522
 523 I commenti di documentazione possono essere inclusi in un qualsiasi documento
 524 di tipo reStructuredText mediante l'apposita direttiva nell'estensione
 525 kernel-doc per Sphinx.
 526
 527 Le direttive kernel-doc sono nel formato::
 528
 529   .. kernel-doc:: source
 530      :option:
 531
 532 Il campo *source* è il percorso ad un file sorgente, relativo alla cartella
 533 principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:
 534
 535 export: *[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
 553 internal: *[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
 564 identifiers: *[ 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
 577 functions: *[ function ...]*
 578   Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.
 579
 580 doc: *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
 593 Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
 594 documentazione presenti nel file sorgente (*source*).
 595
 596 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
 597 in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
 598 lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
 599 dai file sorgenti.
 600
 601 Come utilizzare kernel-doc per generare pagine man
 602 --------------------------------------------------
 603
 604 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
 605 farlo direttamente dai sorgenti del kernel::
 606
 607   $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man