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 .. _it_kernel_doc:
   7
   8 Scrivere i commenti in kernel-doc
   9 =================================
  10
  11 Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione
  12 strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni,
  13 tipi 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
  20 La struttura kernel-doc è estratta a partire dai commenti; da questi viene
  21 generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le
  22 funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni
  23 vengono filtrare per cercare i riferimenti ed i marcatori.
  24
  25 Vedere di seguito per maggiori dettagli.
  26
  27 .. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
  28
  29 Tutte le funzioni esportate verso i moduli esterni utilizzando
  30 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento
  31 kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni
  32 e le strutture dati nei file d'intestazione dovrebbero avere dei commenti
  33 kernel-doc.
  34
  35 È considerata una buona pratica quella di fornire una documentazione formattata
  36 secondo kernel-doc per le funzioni che sono visibili da altri file del kernel
  37 (ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo,
  38 inoltre, di fornire una documentazione kernel-doc anche per procedure private
  39 (ovvero, dichiarate "static") al fine di fornire una struttura più coerente
  40 dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a
  41 discrezione dal manutentore (MAINTAINER) del file sorgente.
  42
  43
  44
  45 Sicuramente la documentazione formattata con kernel-doc è necessaria per
  46 le funzioni che sono esportate verso i moduli esterni utilizzando
  47 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.
  48
  49 Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
  50 per le funzioni che sono visibili da altri file del kernel (ovvero, che non
  51 siano dichiarate utilizzando "static")
  52
  53 Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
  54 anche per procedure private (ovvero, dichiarate "static") al fine di fornire
  55 una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità
  56 più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.
  57
  58 Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse
  59 documentate utilizzando commenti formattati con kernel-doc.
  60
  61 Come formattare i commenti kernel-doc
  62 -------------------------------------
  63
  64 I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma
  65 ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto
  66 del commento è formattato come un normale commento multilinea, ovvero
  67 con un asterisco all'inizio d'ogni riga e che si conclude con ``*/``
  68 su una riga separata.
  69
  70 I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati
  71 appena sopra la funzione od il tipo che descrivono. Questo allo scopo di
  72 aumentare la probabilità che chi cambia il codice si ricordi di aggiornare
  73 anche la documentazione. I commenti kernel-doc di tipo più generale possono
  74 essere posizionati ovunque nel file.
  75
  76 Al fine di verificare che i commenti siano formattati correttamente, potete
  77 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
  78 che questo produca alcuna documentazione. Per esempio::
  79
  80         scripts/kernel-doc -v -none drivers/foo/bar.c
  81
  82 Il formato della documentazione è verificato della procedura di generazione
  83 del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
  84
  85         make W=n
  86
  87 Documentare le funzioni
  88 ------------------------
  89
  90 Generalmente il formato di un commento kernel-doc per funzioni e
  91 macro 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
 116 La descrizione introduttiva (*brief description*) che segue il nome della
 117 funzione può continuare su righe successive e termina con la descrizione di
 118 un argomento, una linea di commento vuota, oppure la fine del commento.
 119
 120 Parametri delle funzioni
 121 ~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito
 124 dopo la descrizione introduttiva.  Non lasciare righe vuote né fra la
 125 descrizione introduttiva e quella degli argomenti, né fra gli argomenti.
 126
 127 Ogni ``@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
 144 Se una funzione ha un numero variabile di argomento, la sua descrizione
 145 dovrebbe essere scritta con la notazione kernel-doc::
 146
 147       * @...: description
 148
 149 Contesto delle funzioni
 150 ~~~~~~~~~~~~~~~~~~~~~~~
 151
 152 Il contesto in cui le funzioni vengono chiamate viene descritto in una
 153 sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità
 154 che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto
 155 d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che
 156 vengano presi dal chiamante.
 157
 158 Esempi::
 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
 168 Valore di ritorno
 169 ~~~~~~~~~~~~~~~~~
 170
 171 Il 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
 199 Documentare strutture, unioni ed enumerazioni
 200 ---------------------------------------------
 201
 202 Generalmente 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
 214 Nell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum``
 215 per descrivere unioni ed enumerati. ``member`` viene usato per indicare i
 216 membri di strutture ed unioni, ma anche i valori di un tipo enumerato.
 217
 218 La descrizione introduttiva (*brief description*) che segue il nome della
 219 funzione può continuare su righe successive e termina con la descrizione di
 220 un argomento, una linea di commento vuota, oppure la fine del commento.
 221
 222 Membri
 223 ~~~~~~
 224
 225 I membri di strutture, unioni ed enumerati devo essere documentati come i
 226 parametri delle funzioni; seguono la descrizione introduttiva e possono
 227 estendersi su più righe.
 228
 229 All'interno d'una struttura o d'un unione, potete utilizzare le etichette
 230 ``private:`` e ``public:``. I campi che sono nell'area ``private:`` non
 231 verranno inclusi nella documentazione finale.
 232
 233 Le etichette ``private:`` e ``public:`` devono essere messe subito dopo
 234 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
 235 fra ``:`` e il marcatore di fine commento ``*/``.
 236
 237 Esempio::
 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
 256 Strutture 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
 307 Commenti in linea per la documentazione dei membri
 308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 309
 310 I membri d'una struttura possono essere documentati in linea all'interno
 311 della definizione stessa. Ci sono due stili: una singola riga di commento
 312 che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come
 313 qualsiasi 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
 345 Documentazione dei tipi di dato
 346 -------------------------------
 347 Generalmente il formato di un commento kernel-doc per typedef è
 348 il seguente::
 349
 350   /**
 351    * typedef type_name - Brief description.
 352    *
 353    * Description of the type.
 354    */
 355
 356 Anche 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
 370 Marcatori e riferimenti
 371 -----------------------
 372
 373 All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
 374 *pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti
 375 del `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
 419 Riferimenti usando reStructuredText
 420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 421
 422 Nei documenti reStructuredText non serve alcuna sintassi speciale per
 423 fare riferimento a funzioni e tipi definiti nei commenti
 424 kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,
 425 e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un
 426 tipo. Per esempio::
 427
 428   See foo()
 429   See struct foo.
 430   See union bar.
 431   See enum baz.
 432   See typedef meh.
 433
 434 Tuttavia, la personalizzazione dei collegamenti è possibile solo con
 435 la 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
 441 Commenti per una documentazione generale
 442 ----------------------------------------
 443
 444 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
 445 dei blocchi di documentazione kernel-doc con un formato libero invece
 446 che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
 447 di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
 448 spiegazione delle operazioni di un driver o di una libreria
 449
 450 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
 451 un titolo.
 452
 453 Generalmente il formato di un commento generico o di visione d'insieme è
 454 il 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
 468 Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file
 469 sorgente, ma anche come identificatore per l'estrazione di questi commenti di
 470 documentazione. Quindi, il titolo dev'essere unico all'interno del file.
 471
 472 Includere i commenti di tipo kernel-doc
 473 =======================================
 474
 475 I commenti di documentazione possono essere inclusi in un qualsiasi documento
 476 di tipo reStructuredText mediante l'apposita direttiva nell'estensione
 477 kernel-doc per Sphinx.
 478
 479 Le direttive kernel-doc sono nel formato::
 480
 481   .. kernel-doc:: source
 482      :option:
 483
 484 Il campo *source* è il percorso ad un file sorgente, relativo alla cartella
 485 principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:
 486
 487 export: *[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
 505 internal: *[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
 516 identifiers: *[ 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
 529 functions: *[ function ...]*
 530   Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.
 531
 532 doc: *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
 545 Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
 546 documentazione presenti nel file sorgente (*source*).
 547
 548 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
 549 in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
 550 lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
 551 dai file sorgenti.
 552
 553 Come utilizzare kernel-doc per generare pagine man
 554 --------------------------------------------------
 555
 556 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
 557 farlo direttamente dai sorgenti del kernel::
 558
 559   $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man