0001 .. include:: ../disclaimer-ita.rst
0002
0003 .. note:: Per leggere la documentazione originale in inglese:
0004 :ref:`Documentation/doc-guide/index.rst <doc_guide>`
0005
0006 .. _it_kernel_doc:
0007
0008 =================================
0009 Scrivere i commenti in kernel-doc
0010 =================================
0011
0012 Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione
0013 strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni,
0014 tipi di dati, e l'architettura del codice.
0015
0016 .. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma
0017 in realtà è molto differente per ragioni storiche. I sorgenti del kernel
0018 contengono decine di migliaia di commenti kernel-doc. Siete pregati
0019 d'attenervi allo stile qui descritto.
0020
0021 La struttura kernel-doc è estratta a partire dai commenti; da questi viene
0022 generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le
0023 funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni
0024 vengono filtrare per cercare i riferimenti ed i marcatori.
0025
0026 Vedere di seguito per maggiori dettagli.
0027
0028 .. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
0029
0030 Tutte le funzioni esportate verso i moduli esterni utilizzando
0031 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento
0032 kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni
0033 e le strutture dati nei file d'intestazione dovrebbero avere dei commenti
0034 kernel-doc.
0035
0036 È considerata una buona pratica quella di fornire una documentazione formattata
0037 secondo kernel-doc per le funzioni che sono visibili da altri file del kernel
0038 (ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo,
0039 inoltre, di fornire una documentazione kernel-doc anche per procedure private
0040 (ovvero, dichiarate "static") al fine di fornire una struttura più coerente
0041 dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a
0042 discrezione dal manutentore (MAINTAINER) del file sorgente.
0043
0044
0045
0046 Sicuramente la documentazione formattata con kernel-doc è necessaria per
0047 le funzioni che sono esportate verso i moduli esterni utilizzando
0048 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.
0049
0050 Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
0051 per le funzioni che sono visibili da altri file del kernel (ovvero, che non
0052 siano dichiarate utilizzando "static")
0053
0054 Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
0055 anche per procedure private (ovvero, dichiarate "static") al fine di fornire
0056 una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità
0057 più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.
0058
0059 Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse
0060 documentate utilizzando commenti formattati con kernel-doc.
0061
0062 Come formattare i commenti kernel-doc
0063 -------------------------------------
0064
0065 I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma
0066 ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto
0067 del commento è formattato come un normale commento multilinea, ovvero
0068 con un asterisco all'inizio d'ogni riga e che si conclude con ``*/``
0069 su una riga separata.
0070
0071 I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati
0072 appena sopra la funzione od il tipo che descrivono. Questo allo scopo di
0073 aumentare la probabilità che chi cambia il codice si ricordi di aggiornare
0074 anche la documentazione. I commenti kernel-doc di tipo più generale possono
0075 essere posizionati ovunque nel file.
0076
0077 Al fine di verificare che i commenti siano formattati correttamente, potete
0078 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
0079 che questo produca alcuna documentazione. Per esempio::
0080
0081 scripts/kernel-doc -v -none drivers/foo/bar.c
0082
0083 Il formato della documentazione è verificato della procedura di generazione
0084 del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
0085
0086 make W=n
0087
0088 Documentare le funzioni
0089 ------------------------
0090
0091 Generalmente il formato di un commento kernel-doc per funzioni e
0092 macro simil-funzioni è il seguente::
0093
0094 /**
0095 * function_name() - Brief description of function.
0096 * @arg1: Describe the first argument.
0097 * @arg2: Describe the second argument.
0098 * One can provide multiple line descriptions
0099 * for arguments.
0100 *
0101 * A longer description, with more discussion of the function function_name()
0102 * that might be useful to those using or modifying it. Begins with an
0103 * empty comment line, and may include additional embedded empty
0104 * comment lines.
0105 *
0106 * The longer description may have multiple paragraphs.
0107 *
0108 * Context: Describes whether the function can sleep, what locks it takes,
0109 * releases, or expects to be held. It can extend over multiple
0110 * lines.
0111 * Return: Describe the return value of function_name.
0112 *
0113 * The return value description can also have multiple paragraphs, and should
0114 * be placed at the end of the comment block.
0115 */
0116
0117 La descrizione introduttiva (*brief description*) che segue il nome della
0118 funzione può continuare su righe successive e termina con la descrizione di
0119 un argomento, una linea di commento vuota, oppure la fine del commento.
0120
0121 Parametri delle funzioni
0122 ~~~~~~~~~~~~~~~~~~~~~~~~
0123
0124 Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito
0125 dopo la descrizione introduttiva. Non lasciare righe vuote né fra la
0126 descrizione introduttiva e quella degli argomenti, né fra gli argomenti.
0127
0128 Ogni ``@argument:`` può estendersi su più righe.
0129
0130 .. note::
0131
0132 Se la descrizione di ``@argument:`` si estende su più righe,
0133 la continuazione dovrebbe iniziare alla stessa colonna della riga
0134 precedente::
0135
0136 * @argument: some long description
0137 * that continues on next lines
0138
0139 or::
0140
0141 * @argument:
0142 * some long description
0143 * that continues on next lines
0144
0145 Se una funzione ha un numero variabile di argomento, la sua descrizione
0146 dovrebbe essere scritta con la notazione kernel-doc::
0147
0148 * @...: description
0149
0150 Contesto delle funzioni
0151 ~~~~~~~~~~~~~~~~~~~~~~~
0152
0153 Il contesto in cui le funzioni vengono chiamate viene descritto in una
0154 sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità
0155 che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto
0156 d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che
0157 vengano presi dal chiamante.
0158
0159 Esempi::
0160
0161 * Context: Any context.
0162 * Context: Any context. Takes and releases the RCU lock.
0163 * Context: Any context. Expects <lock> to be held by caller.
0164 * Context: Process context. May sleep if @gfp flags permit.
0165 * Context: Process context. Takes and releases <mutex>.
0166 * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
0167 * Context: Interrupt context.
0168
0169 Valore di ritorno
0170 ~~~~~~~~~~~~~~~~~
0171
0172 Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome
0173 ``Return``.
0174
0175 .. note::
0176
0177 #) La descrizione multiriga non riconosce il termine d'una riga, per cui
0178 se provate a formattare bene il vostro testo come nel seguente esempio::
0179
0180 * Return:
0181 * 0 - OK
0182 * -EINVAL - invalid argument
0183 * -ENOMEM - out of memory
0184
0185 le righe verranno unite e il risultato sarà::
0186
0187 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
0188
0189 Quindi, se volete che le righe vengano effettivamente generate, dovete
0190 utilizzare una lista ReST, ad esempio::
0191
0192 * Return:
0193 * * 0 - OK to runtime suspend the device
0194 * * -EBUSY - Device should not be runtime suspended
0195
0196 #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai
0197 due punti, allora ognuna di queste frasi verrà considerata come il nome
0198 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.
0199
0200 Documentare strutture, unioni ed enumerazioni
0201 ---------------------------------------------
0202
0203 Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
0204
0205 /**
0206 * struct struct_name - Brief description.
0207 * @member1: Description of member1.
0208 * @member2: Description of member2.
0209 * One can provide multiple line descriptions
0210 * for members.
0211 *
0212 * Description of the structure.
0213 */
0214
0215 Nell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum``
0216 per descrivere unioni ed enumerati. ``member`` viene usato per indicare i
0217 membri di strutture ed unioni, ma anche i valori di un tipo enumerato.
0218
0219 La descrizione introduttiva (*brief description*) che segue il nome della
0220 funzione può continuare su righe successive e termina con la descrizione di
0221 un argomento, una linea di commento vuota, oppure la fine del commento.
0222
0223 Membri
0224 ~~~~~~
0225
0226 I membri di strutture, unioni ed enumerati devo essere documentati come i
0227 parametri delle funzioni; seguono la descrizione introduttiva e possono
0228 estendersi su più righe.
0229
0230 All'interno d'una struttura o d'un unione, potete utilizzare le etichette
0231 ``private:`` e ``public:``. I campi che sono nell'area ``private:`` non
0232 verranno inclusi nella documentazione finale.
0233
0234 Le etichette ``private:`` e ``public:`` devono essere messe subito dopo
0235 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
0236 fra ``:`` e il marcatore di fine commento ``*/``.
0237
0238 Esempio::
0239
0240 /**
0241 * struct my_struct - short description
0242 * @a: first member
0243 * @b: second member
0244 * @d: fourth member
0245 *
0246 * Longer description
0247 */
0248 struct my_struct {
0249 int a;
0250 int b;
0251 /* private: internal use only */
0252 int c;
0253 /* public: the next one is public */
0254 int d;
0255 };
0256
0257 Strutture ed unioni annidate
0258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0259
0260 È possibile documentare strutture ed unioni annidate, ad esempio::
0261
0262 /**
0263 * struct nested_foobar - a struct with nested unions and structs
0264 * @memb1: first member of anonymous union/anonymous struct
0265 * @memb2: second member of anonymous union/anonymous struct
0266 * @memb3: third member of anonymous union/anonymous struct
0267 * @memb4: fourth member of anonymous union/anonymous struct
0268 * @bar: non-anonymous union
0269 * @bar.st1: struct st1 inside @bar
0270 * @bar.st2: struct st2 inside @bar
0271 * @bar.st1.memb1: first member of struct st1 on union bar
0272 * @bar.st1.memb2: second member of struct st1 on union bar
0273 * @bar.st2.memb1: first member of struct st2 on union bar
0274 * @bar.st2.memb2: second member of struct st2 on union bar
0275 */
0276 struct nested_foobar {
0277 /* Anonymous union/struct*/
0278 union {
0279 struct {
0280 int memb1;
0281 int memb2;
0282 }
0283 struct {
0284 void *memb3;
0285 int memb4;
0286 }
0287 }
0288 union {
0289 struct {
0290 int memb1;
0291 int memb2;
0292 } st1;
0293 struct {
0294 void *memb1;
0295 int memb2;
0296 } st2;
0297 } bar;
0298 };
0299
0300 .. note::
0301
0302 #) Quando documentate una struttura od unione annidata, ad esempio
0303 di nome ``foo``, il suo campo ``bar`` dev'essere documentato
0304 usando ``@foo.bar:``
0305 #) Quando la struttura od unione annidata è anonima, il suo campo
0306 ``bar`` dev'essere documentato usando ``@bar:``
0307
0308 Commenti in linea per la documentazione dei membri
0309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0310
0311 I membri d'una struttura possono essere documentati in linea all'interno
0312 della definizione stessa. Ci sono due stili: una singola riga di commento
0313 che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come
0314 qualsiasi altro commento kernel-doc::
0315
0316 /**
0317 * struct foo - Brief description.
0318 * @foo: The Foo member.
0319 */
0320 struct foo {
0321 int foo;
0322 /**
0323 * @bar: The Bar member.
0324 */
0325 int bar;
0326 /**
0327 * @baz: The Baz member.
0328 *
0329 * Here, the member description may contain several paragraphs.
0330 */
0331 int baz;
0332 union {
0333 /** @foobar: Single line description. */
0334 int foobar;
0335 };
0336 /** @bar2: Description for struct @bar2 inside @foo */
0337 struct {
0338 /**
0339 * @bar2.barbar: Description for @barbar inside @foo.bar2
0340 */
0341 int barbar;
0342 } bar2;
0343 };
0344
0345
0346 Documentazione dei tipi di dato
0347 -------------------------------
0348 Generalmente il formato di un commento kernel-doc per typedef è
0349 il seguente::
0350
0351 /**
0352 * typedef type_name - Brief description.
0353 *
0354 * Description of the type.
0355 */
0356
0357 Anche i tipi di dato per prototipi di funzione possono essere documentati::
0358
0359 /**
0360 * typedef type_name - Brief description.
0361 * @arg1: description of arg1
0362 * @arg2: description of arg2
0363 *
0364 * Description of the type.
0365 *
0366 * Context: Locking context.
0367 * Return: Meaning of the return value.
0368 */
0369 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
0370
0371 Marcatori e riferimenti
0372 -----------------------
0373
0374 All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
0375 *pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti
0376 del `dominio Sphinx per il C`_.
0377
0378 .. attention:: Questi sono riconosciuti **solo** all'interno di commenti
0379 kernel-doc, e **non** all'interno di documenti reStructuredText.
0380
0381 ``funcname()``
0382 Riferimento ad una funzione.
0383
0384 ``@parameter``
0385 Nome di un parametro di una funzione (nessun riferimento, solo formattazione).
0386
0387 ``%CONST``
0388 Il nome di una costante (nessun riferimento, solo formattazione)
0389
0390 ````literal````
0391 Un blocco di testo che deve essere riportato così com'è. La rappresentazione
0392 finale utilizzerà caratteri a ``spaziatura fissa``.
0393
0394 Questo è utile se dovete utilizzare caratteri speciali che altrimenti
0395 potrebbero assumere un significato diverso in kernel-doc o in reStructuredText
0396
0397 Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph``
0398 all'interno della descrizione di una funzione.
0399
0400 ``$ENVVAR``
0401 Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione).
0402
0403 ``&struct name``
0404 Riferimento ad una struttura.
0405
0406 ``&enum name``
0407 Riferimento ad un'enumerazione.
0408
0409 ``&typedef name``
0410 Riferimento ad un tipo di dato.
0411
0412 ``&struct_name->member`` or ``&struct_name.member``
0413 Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà
0414 la struttura o l'unione, non il memembro.
0415
0416 ``&name``
0417 Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento
0418 completo come descritto sopra. Questo è dedicato ai commenti obsoleti.
0419
0420 Riferimenti usando reStructuredText
0421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0422
0423 Nei documenti reStructuredText non serve alcuna sintassi speciale per
0424 fare riferimento a funzioni e tipi definiti nei commenti
0425 kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,
0426 e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un
0427 tipo. Per esempio::
0428
0429 See foo()
0430 See struct foo.
0431 See union bar.
0432 See enum baz.
0433 See typedef meh.
0434
0435 Tuttavia, la personalizzazione dei collegamenti è possibile solo con
0436 la seguente sintassi::
0437
0438 See :c:func:`my custom link text for function foo <foo>`.
0439 See :c:type:`my custom link text for struct bar <bar>`.
0440
0441
0442 Commenti per una documentazione generale
0443 ----------------------------------------
0444
0445 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
0446 dei blocchi di documentazione kernel-doc con un formato libero invece
0447 che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
0448 di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
0449 spiegazione delle operazioni di un driver o di una libreria
0450
0451 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
0452 un titolo.
0453
0454 Generalmente il formato di un commento generico o di visione d'insieme è
0455 il seguente::
0456
0457 /**
0458 * DOC: Theory of Operation
0459 *
0460 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
0461 * want it to do, at any time. It reads your mind. Here's how it works.
0462 *
0463 * foo bar splat
0464 *
0465 * The only drawback to this gizmo is that is can sometimes damage
0466 * hardware, software, or its subject(s).
0467 */
0468
0469 Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file
0470 sorgente, ma anche come identificatore per l'estrazione di questi commenti di
0471 documentazione. Quindi, il titolo dev'essere unico all'interno del file.
0472
0473 =======================================
0474 Includere i commenti di tipo kernel-doc
0475 =======================================
0476
0477 I commenti di documentazione possono essere inclusi in un qualsiasi documento
0478 di tipo reStructuredText mediante l'apposita direttiva nell'estensione
0479 kernel-doc per Sphinx.
0480
0481 Le direttive kernel-doc sono nel formato::
0482
0483 .. kernel-doc:: source
0484 :option:
0485
0486 Il campo *source* è il percorso ad un file sorgente, relativo alla cartella
0487 principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:
0488
0489 export: *[source-pattern ...]*
0490 Include la documentazione per tutte le funzioni presenti nel file sorgente
0491 (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o
0492 ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern*
0493 specificato.
0494
0495 Il campo *source-patter* è utile quando i commenti kernel-doc sono stati
0496 scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e
0497 ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni.
0498
0499 Esempi::
0500
0501 .. kernel-doc:: lib/bitmap.c
0502 :export:
0503
0504 .. kernel-doc:: include/net/mac80211.h
0505 :export: net/mac80211/*.c
0506
0507 internal: *[source-pattern ...]*
0508 Include la documentazione per tutte le funzioni ed i tipi presenti nel file
0509 sorgente (*source*) che **non** sono stati esportati utilizzando
0510 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi
0511 altro *source-pattern* specificato.
0512
0513 Esempio::
0514
0515 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
0516 :internal:
0517
0518 identifiers: *[ function/type ...]*
0519 Include la documentazione per ogni *function* e *type* in *source*.
0520 Se non vengono esplicitamente specificate le funzioni da includere, allora
0521 verranno incluse tutte quelle disponibili in *source*.
0522
0523 Esempi::
0524
0525 .. kernel-doc:: lib/bitmap.c
0526 :identifiers: bitmap_parselist bitmap_parselist_user
0527
0528 .. kernel-doc:: lib/idr.c
0529 :identifiers:
0530
0531 functions: *[ function ...]*
0532 Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.
0533
0534 doc: *title*
0535 Include la documentazione del paragrafo ``DOC:`` identificato dal titolo
0536 (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono
0537 permessi; non virgolettate *title*. Il campo *title* è utilizzato per
0538 identificare un paragrafo e per questo non viene incluso nella documentazione
0539 finale. Verificate d'avere l'intestazione appropriata nei documenti
0540 reStructuredText.
0541
0542 Esempio::
0543
0544 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
0545 :doc: High Definition Audio over HDMI and Display Port
0546
0547 Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
0548 documentazione presenti nel file sorgente (*source*).
0549
0550 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
0551 in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
0552 lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
0553 dai file sorgenti.
0554
0555 Come utilizzare kernel-doc per generare pagine man
0556 --------------------------------------------------
0557
0558 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
0559 farlo direttamente dai sorgenti del kernel::
0560
0561 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
