608 lines · plain
1.. include:: ../disclaimer-ita.rst2 3.. note:: Per leggere la documentazione originale in inglese:4 :ref:`Documentation/doc-guide/index.rst <doc_guide>`5 6.. title:: Commenti in kernel-doc7 8.. _it_kernel_doc:9 10=================================11Scrivere i commenti in kernel-doc12=================================13 14Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione15strutturanti 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 ma19 in realtà è molto differente per ragioni storiche. I sorgenti del kernel20 contengono decine di migliaia di commenti kernel-doc. Siete pregati21 d'attenervi allo stile qui descritto.22 23La struttura kernel-doc è estratta a partire dai commenti; da questi viene24generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le25funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni26vengono 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.html31 32Tutte le funzioni esportate verso i moduli esterni utilizzando33``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento34kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni35e le strutture dati nei file d'intestazione dovrebbero avere dei commenti36kernel-doc.37 38È considerata una buona pratica quella di fornire una documentazione formattata39secondo kernel-doc per le funzioni che sono visibili da altri file del kernel40(ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo,41inoltre, di fornire una documentazione kernel-doc anche per procedure private42(ovvero, dichiarate "static") al fine di fornire una struttura più coerente43dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a44discrezione dal manutentore (MAINTAINER) del file sorgente.45 46 47 48Sicuramente la documentazione formattata con kernel-doc è necessaria per49le funzioni che sono esportate verso i moduli esterni utilizzando50``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.51 52Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc53per le funzioni che sono visibili da altri file del kernel (ovvero, che non54siano dichiarate utilizzando "static")55 56Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc57anche per procedure private (ovvero, dichiarate "static") al fine di fornire58una 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'esse62documentate utilizzando commenti formattati con kernel-doc.63 64Come formattare i commenti kernel-doc65-------------------------------------66 67I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma68``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto69del commento è formattato come un normale commento multilinea, ovvero70con 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 posizionati74appena sopra la funzione od il tipo che descrivono. Questo allo scopo di75aumentare la probabilità che chi cambia il codice si ricordi di aggiornare76anche la documentazione. I commenti kernel-doc di tipo più generale possono77essere posizionati ovunque nel file.78 79Al fine di verificare che i commenti siano formattati correttamente, potete80eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza81che questo produca alcuna documentazione. Per esempio::82 83 scripts/kernel-doc -v -none drivers/foo/bar.c84 85Il formato della documentazione è verificato della procedura di generazione86del kernel quando viene richiesto di effettuare dei controlli extra con GCC::87 88 make W=n89 90Documentare le funzioni91------------------------92 93Generalmente il formato di un commento kernel-doc per funzioni e94macro 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 descriptions101 * 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 an105 * empty comment line, and may include additional embedded empty106 * 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 multiple112 * lines.113 * Return: Describe the return value of function_name.114 *115 * The return value description can also have multiple paragraphs, and should116 * be placed at the end of the comment block.117 */118 119La descrizione introduttiva (*brief description*) che segue il nome della120funzione può continuare su righe successive e termina con la descrizione di121un argomento, una linea di commento vuota, oppure la fine del commento.122 123Parametri delle funzioni124~~~~~~~~~~~~~~~~~~~~~~~~125 126Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito127dopo la descrizione introduttiva. Non lasciare righe vuote né fra la128descrizione 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 riga136 precedente::137 138 * @argument: some long description139 * that continues on next lines140 141 or::142 143 * @argument:144 * some long description145 * that continues on next lines146 147Se una funzione ha un numero variabile di argomento, la sua descrizione148dovrebbe essere scritta con la notazione kernel-doc::149 150 * @...: description151 152Contesto delle funzioni153~~~~~~~~~~~~~~~~~~~~~~~154 155Il contesto in cui le funzioni vengono chiamate viene descritto in una156sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità157che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto158d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che159vengano 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 ritorno172~~~~~~~~~~~~~~~~~173 174Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome175``Return``.176 177.. note::178 179 #) La descrizione multiriga non riconosce il termine d'una riga, per cui180 se provate a formattare bene il vostro testo come nel seguente esempio::181 182 * Return:183 * %0 - OK184 * %-EINVAL - invalid argument185 * %-ENOMEM - out of memory186 187 le righe verranno unite e il risultato sarà::188 189 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory190 191 Quindi, se volete che le righe vengano effettivamente generate, dovete192 utilizzare una lista ReST, ad esempio::193 194 * Return:195 * * %0 - OK to runtime suspend the device196 * * %-EBUSY - Device should not be runtime suspended197 198 #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai199 due punti, allora ognuna di queste frasi verrà considerata come il nome200 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.201 202Documentare strutture, unioni ed enumerazioni203---------------------------------------------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 descriptions212 * 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 i219membri di strutture ed unioni, ma anche i valori di un tipo enumerato.220 221La descrizione introduttiva (*brief description*) che segue il nome della222funzione può continuare su righe successive e termina con la descrizione di223un argomento, una linea di commento vuota, oppure la fine del commento.224 225Membri226~~~~~~227 228I membri di strutture, unioni ed enumerati devo essere documentati come i229parametri delle funzioni; seguono la descrizione introduttiva e possono230estendersi su più righe.231 232All'interno d'una struttura o d'un unione, potete utilizzare le etichette233``private:`` e ``public:``. I campi che sono nell'area ``private:`` non234verranno inclusi nella documentazione finale.235 236Le etichette ``private:`` e ``public:`` devono essere messe subito dopo237il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti238fra ``:`` e il marcatore di fine commento ``*/``.239 240Esempio::241 242 /**243 * struct my_struct - short description244 * @a: first member245 * @b: second member246 * @d: fourth member247 *248 * Longer description249 */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 annidate260~~~~~~~~~~~~~~~~~~~~~~~~~~~~261 262È possibile documentare strutture ed unioni annidate, ad esempio::263 264 /**265 * struct nested_foobar - a struct with nested unions and structs266 * @memb1: first member of anonymous union/anonymous struct267 * @memb2: second member of anonymous union/anonymous struct268 * @memb3: third member of anonymous union/anonymous struct269 * @memb4: fourth member of anonymous union/anonymous struct270 * @bar: non-anonymous union271 * @bar.st1: struct st1 inside @bar272 * @bar.st2: struct st2 inside @bar273 * @bar.st1.memb1: first member of struct st1 on union bar274 * @bar.st1.memb2: second member of struct st1 on union bar275 * @bar.st2.memb1: first member of struct st2 on union bar276 * @bar.st2.memb2: second member of struct st2 on union bar277 */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 esempio305 di nome ``foo``, il suo campo ``bar`` dev'essere documentato306 usando ``@foo.bar:``307 #) Quando la struttura od unione annidata è anonima, il suo campo308 ``bar`` dev'essere documentato usando ``@bar:``309 310Commenti in linea per la documentazione dei membri311~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~312 313I membri d'una struttura possono essere documentati in linea all'interno314della definizione stessa. Ci sono due stili: una singola riga di commento315che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come316qualsiasi 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.bar2342 */343 int barbar;344 } bar2;345 };346 347 348Documentazione dei tipi di dato349-------------------------------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 arg1364 * @arg2: description of arg2365 *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 373Documentazione di macro simili a oggetti374----------------------------------------375 376Le macro simili a oggetti si distinguono dalle macro simili a funzione. Esse si377distinguono in base al fatto che il nome della macro simile a funzione sia378immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a379oggetti no.380 381Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.382Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un383elenco di parametri.384 385Il 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 393Esempio::394 395 /**396 * define MAX_ERRNO - maximum errno value that is supported397 *398 * Kernel pointers have redundant information, so we can use a399 * scheme where we can return either an error code or a normal400 * pointer with the same return value.401 */402 #define MAX_ERRNO 4095403 404Esempio::405 406 /**407 * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \408 * Initializes struct drm_plane_helper_funcs for VRAM handling409 *410 * This macro initializes struct drm_plane_helper_funcs to use the411 * 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_fb416 417Marcatori e riferimenti418-----------------------419 420All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti421*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti422del `dominio Sphinx per il C`_.423 424.. attention:: Questi sono riconosciuti **solo** all'interno di commenti425 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 rappresentazione438 finale utilizzerà caratteri a ``spaziatura fissa``.439 440 Questo è utile se dovete utilizzare caratteri speciali che altrimenti441 potrebbero assumere un significato diverso in kernel-doc o in reStructuredText442 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 riferimento464 completo come descritto sopra. Questo è dedicato ai commenti obsoleti.465 466Riferimenti usando reStructuredText467~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~468 469Nei documenti reStructuredText non serve alcuna sintassi speciale per470fare riferimento a funzioni e tipi definiti nei commenti471kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,472e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un473tipo. Per esempio::474 475 See foo()476 See struct foo.477 See union bar.478 See enum baz.479 See typedef meh.480 481Tuttavia, la personalizzazione dei collegamenti è possibile solo con482la 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 488Commenti per una documentazione generale489----------------------------------------490 491Al fine d'avere il codice ed i commenti nello stesso file, potete includere492dei blocchi di documentazione kernel-doc con un formato libero invece493che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi494di dato. Per esempio, questo tipo di commento potrebbe essere usato per la495spiegazione delle operazioni di un driver o di una libreria496 497Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato498un titolo.499 500Generalmente il formato di un commento generico o di visione d'insieme è501il seguente::502 503 /**504 * DOC: Theory of Operation505 *506 * The whizbang foobar is a dilly of a gizmo. It can do whatever you507 * want it to do, at any time. It reads your mind. Here's how it works.508 *509 * foo bar splat510 *511 * The only drawback to this gizmo is that is can sometimes damage512 * hardware, software, or its subject(s).513 */514 515Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file516sorgente, ma anche come identificatore per l'estrazione di questi commenti di517documentazione. Quindi, il titolo dev'essere unico all'interno del file.518 519=======================================520Includere i commenti di tipo kernel-doc521=======================================522 523I commenti di documentazione possono essere inclusi in un qualsiasi documento524di tipo reStructuredText mediante l'apposita direttiva nell'estensione525kernel-doc per Sphinx.526 527Le direttive kernel-doc sono nel formato::528 529 .. kernel-doc:: source530 :option:531 532Il campo *source* è il percorso ad un file sorgente, relativo alla cartella533principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:534 535export: *[source-pattern ...]*536 Include la documentazione per tutte le funzioni presenti nel file sorgente537 (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o538 ``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 stati542 scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e543 ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni.544 545 Esempi::546 547 .. kernel-doc:: lib/bitmap.c548 :export:549 550 .. kernel-doc:: include/net/mac80211.h551 :export: net/mac80211/*.c552 553internal: *[source-pattern ...]*554 Include la documentazione per tutte le funzioni ed i tipi presenti nel file555 sorgente (*source*) che **non** sono stati esportati utilizzando556 ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi557 altro *source-pattern* specificato.558 559 Esempio::560 561 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c562 :internal:563 564identifiers: *[ function/type ...]*565 Include la documentazione per ogni *function* e *type* in *source*.566 Se non vengono esplicitamente specificate le funzioni da includere, allora567 verranno incluse tutte quelle disponibili in *source*.568 569 Esempi::570 571 .. kernel-doc:: lib/bitmap.c572 :identifiers: bitmap_parselist bitmap_parselist_user573 574 .. kernel-doc:: lib/idr.c575 :identifiers:576 577functions: *[ function ...]*578 Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.579 580doc: *title*581 Include la documentazione del paragrafo ``DOC:`` identificato dal titolo582 (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono583 permessi; non virgolettate *title*. Il campo *title* è utilizzato per584 identificare un paragrafo e per questo non viene incluso nella documentazione585 finale. Verificate d'avere l'intestazione appropriata nei documenti586 reStructuredText.587 588 Esempio::589 590 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c591 :doc: High Definition Audio over HDMI and Display Port592 593Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di594documentazione presenti nel file sorgente (*source*).595 596L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare597in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato598lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione599dai file sorgenti.600 601Come utilizzare kernel-doc per generare pagine man602--------------------------------------------------603 604Se volete utilizzare kernel-doc solo per generare delle pagine man, potete605farlo direttamente dai sorgenti del kernel::606 607 $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man608